From d9fcba1fc9819764bbf6205f0cf3d58a0d4c24c5 Mon Sep 17 00:00:00 2001 From: Dawid Makowski Date: Sun, 24 Mar 2024 23:04:12 +0700 Subject: [PATCH 1/6] 1.1.0 updates --- .gitignore | 20 +- CHANGELOG.md | 117 ++++- README.md | 412 +++++++++++++---- composer.json | 32 +- composer.lock | 663 --------------------------- src/Dto/JobDescriptionParameters.php | 24 +- src/Dto/SharpApiSubscriptionInfo.php | 54 +++ src/Enums/SharpApiJobTypeEnum.php | 32 ++ src/Enums/SharpApiVoiceTone.php | 66 +++ src/SharpApiService.php | 472 ++++++++++++++----- 10 files changed, 1000 insertions(+), 892 deletions(-) delete mode 100644 composer.lock create mode 100644 src/Dto/SharpApiSubscriptionInfo.php create mode 100644 src/Enums/SharpApiVoiceTone.php diff --git a/.gitignore b/.gitignore index e135131..cc74682 100644 --- a/.gitignore +++ b/.gitignore @@ -3,18 +3,6 @@ node_modules/ npm-debug.log yarn-error.log -# Laravel 4 specific -bootstrap/compiled.php -app/storage/ - -# Laravel 5 & Lumen specific -public/storage -public/hot - -# Laravel 5 & Lumen specific with changed public path -public_html/storage -public_html/hot - storage/*.key .env Homestead.yaml @@ -22,3 +10,11 @@ Homestead.json /.vagrant .phpunit.result.cache .idea + +build +composer.lock +.phpunit.result.cache +.php-cs-fixer.cache +coverage +phpstan.neon + diff --git a/CHANGELOG.md b/CHANGELOG.md index cff8107..794fe50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,118 @@ # Changelog -- v1.0.2 initial release +## March 23, 2023 - v1.1.0 update -All notable changes to `sharpapi-php-client` will be documented in this file. +### 1. new methods added + +#### 1.2. Paraphrase text: `paraphrase()` +Generates a paraphrased version of the provided text. + +[Check Documentation](https://documenter.getpostman.com/view/31106842/2s9Ye8faUp#aea28008-ac67-4245-a79b-26788bce3f44) + +#### 1.2 Proofread & Grammar Check: `proofread()` + +Proofreads (and checks grammar) of the provided text. + +[Check Documentation](https://documenter.getpostman.com/view/31106842/2s9Ye8faUp#dcb4a490-1243-4001-93fc-652c570dbcd7) + +#### 1.3 Subscription Info / Quota Check: `quota()` + +Endpoint to check details regarding the subscription's current period. + +```json +{ + "timestamp": "2024-03-19T12:49:41.445736Z", + "on_trial": false, + "trial_ends": "2024-03-17T07:57:46.000000Z", + "subscribed": true, + "current_subscription_start": "2024-03-18T12:37:39.000000Z", + "current_subscription_end": "2024-04-18T12:37:39.000000Z", + "subscription_words_quota": 100000, + "subscription_words_used": 9608, + "subscription_words_used_percentage": 0.1 +} +``` +* "subscription_words_used_percentage" is a percentage of current monthly quota usage +* and might serve as an alert to the user of the depleted credits. +* With a value above 80%, it's advised to subscribe to more credits +* at https://sharpapi.com/dashboard/credits to avoid service disruption. + +[Check Documentation](https://documenter.getpostman.com/view/31106842/2s9Ye8faUp#7c401a21-8354-4589-a20a-573d1ae00d65) + +#### 1.4 Subscription Info / Quota Check: `ping()` + +Simple PING endpoint to check the availability of the API and it's internal timze zone (timestamp). + +```json +{ + "ping": "pong", + "timestamp": "2024-03-12T08:50:11.188308Z" +} +``` + +[Check Documentation](https://documenter.getpostman.com/view/31106842/2s9Ye8faUp#12a4aa9e-15cd-49a9-84ff-204ddc1116a3) + +### 2. New Parameters added + +#### 2.1 `max_quantity` - allows to limit the amount of returned items + +**Added to methods:** +- E-commerce > Product Categories / `productCategories()` +- Travel, Tourism & Hospitality > Tours & Activities Product Categories / `toursAndActivitiesProductCategories()` +- Travel, Tourism & Hospitality > Hospitality Product Categories / `hospitalityProductCategories()` +- HR Tech > Related Job Positions / `relatedJobPositions()` +- HR Tech > Related Skills / `relatedSkills()` + +#### 2.2 `max_length` - allows to instruct AI model to limit the output of generated text + +Please keep in mind that max_length serves as a strong suggestion for the Language Model, +rather than a strict requirement, to maintain the general sense of the outcome. + +**Added to methods:** +- E-commerce > Generate Product Intro / `generateProductIntro()` +- E-commerce > Generate Thank You E-mail / `generateThankYouEmail()` +- Content & Marketing Automation > Summarize Content / `summarizeText()` +- Content & Marketing Automation > Paraphrase Text / `paraphrase()` + +#### 2.3 `voice_tone` - Tone of voice of the generated text + +You can set your preferred writing style by providing +an optional voice_tone parameter. It can be adjectives like +`funny` or `joyous`, or even the name of a famous writer. +You can provide multiple tones at the same time. + +**Added to methods:** +- SEO > Generate SEO Tags / `generateSeoTags()` +- Content & Marketing Automation > Generate Keywords/Tags / `generateKeywords()` +- Content & Marketing Automation > Summarize Content / `summarizeText()` +- Content & Marketing Automation > Paraphrase Text / `paraphrase()` +- Content & Marketing Automation > Translate Text / `translate()` +- Travel, Tourism & Hospitality > Tours & Activities Product Categories / `toursAndActivitiesProductCategories()` +- Travel, Tourism & Hospitality > Hospitality Product Categories / `hospitalityProductCategories()` +- HR Tech > Generate Job Description / `generateJobDescription()` +- E-commerce > Product Categories / `productCategories()` +- E-commerce > Generate Product Intro / `generateProductIntro()` +- E-commerce > Generate Thank You E-mail / `generateThankYouEmail()` + +#### 2.4 `context` - adds more context/instructions for content processing + +**Added to methods:** +- HR Tech > Generate Job Description / `generateJobDescription()` +- E-commerce > Generate Thank You E-mail / `generateThankYouEmail()` +- E-commerce > Product Categories / `productCategories()` +- Travel, Tourism & Hospitality > Tours & Activities Product Categories / `toursAndActivitiesProductCategories()` +- Travel, Tourism & Hospitality > Hospitality Product Categories / `hospitalityProductCategories()` +- Content & Marketing Automation > Translate Text / `translate()` +- Content & Marketing Automation > Paraphrase Text / `paraphrase()` + +### 3.0 Added ENV variable to set custom User-Agent for Affiliate Program members. + +Now you can set this inside `.env` file of your app: +```bash +SHARP_API_USER_AGENT="SharpAPIPHPAgent/1.1.0" +``` + +More info at https://sharpapi.com/affiliate_program + +## December 10, 2023 - v1.0.2 +- v1.0.2 initial release \ No newline at end of file diff --git a/README.md b/README.md index 40039b1..b642a9d 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ ![SharpAPI GitHub cover](https://sharpapi.com/sharpapi-github-php-bg.jpg "SharpAPI Laravel Client") -# SharpAPI PHP Client +# SharpAPI PHP Client - #AI Programming Interface -### AI-Powered Swiss Army Knife API for every software developer +### 🚀 AI-Powered Swiss Army Knife API ## Save countless hours and supercharge your app with AI capabilities in just 2 lines of code. @@ -19,28 +19,26 @@ See more at [SharpAPI.com Website »](https://sharpapi.com/) - PHP >= 8.1 -## What can it do for you? - -* **E-commerce** - - Quickly generate engaging product introductions to attract customers. - - Automatically create personalized thank-you emails for enhanced customer experience. - - Streamline product categorization for a well-organized catalog. - - Sentiment Analysis: Understand and analyze sentiment in product reviews for data-driven decision-making. -* **Content & Marketing Automation** - - Easily translate text for a global audience. - - Spam Content Detection: Identify and filter out spam content effectively. - - Contact Information Extraction: Extract phone numbers and email addresses from non-standard formats for - streamlined communication. - - Generate concise summaries and unique keywords/tags for improved content consumption. - - Boost SEO efforts by automatically generating META tags based on content. -* **HR Tech** - - Generate complex job descriptions effortlessly, saving time in the hiring process. - - Skills and Position Insights: Identify related job positions and skills to streamline recruitment. - - Automated Resume Parsing: Efficiently parse and extract information from resumes files for easy processing. -* **Travel, Tourism & Hospitality** - - Analyze sentiment in travel reviews to improve services. - - Streamline categorization for tours, activities, and hospitality products. - +## ⛲ What can it do for you? +* 🛒 **E-commerce** + - Quickly generate engaging product introductions to attract customers. + - Automatically create personalized thank-you emails for enhanced customer experience. + - Streamline product categorization for a well-organized catalog. + - Sentiment Analysis: Understand and analyze sentiment in product reviews for data-driven decision-making. +* 📝️ **Content & Marketing Automation** + - Easily translate text for a global audience. + - Paraphrase and proofread any text (including grammar check) + - Spam Content Detection: Identify and filter out spam content effectively. + - Contact Information Extraction: Extract phone numbers and email addresses from non-standard formats for streamlined communication. + - Generate concise summaries and unique keywords/tags for improved content consumption. + - Boost SEO efforts by automatically generating META tags based on content. +* ‍💻 **HR Tech** + - Generate complex job descriptions effortlessly, saving time in the hiring process. + - Skills and Position Insights: Identify related job positions and skills to streamline recruitment. + - Automated Resume Parsing: Efficiently parse and extract information from resumes files for easy processing. +* ✈️ **Travel, Tourism & Hospitality** + - Analyze sentiment in travel reviews to improve services. + - Streamline categorization for tours, activities, and hospitality products. ## Features Please refer to the official: @@ -62,20 +60,29 @@ Please refer to the official: ## Installation 1. You can install the package via composer: - ```bash - composer require sharpapi/sharpapi-php-client - ``` +```bash +composer require sharpapi/sharpapi-php-client +``` + 2. Register at [SharpApi.com](https://sharpapi.com/) and get the API key. - **That's it!** + +3. **That's it!** ## Usage ### Simple example ```php -$sharpApi = new \SharpAPI\SharpApiService\SharpApiService('8bKzQl3cwckfVsnsN8T8p4BsACkziEQJ72U4pXpQ'); - -$statusUrl = $sharpApi->productCategories('Lenovo Chromebook Laptop (2023), 14" FHD Touchscreen Slim 3, 8-Core MediaTek Kompanio 520 CPU, 4GB RAM, 128GB Storage'); +$sharpApi = new \SharpAPI\SharpApiService\SharpApiService(SHARP_API_KEY); + +$statusUrl = $sharpApi->productCategories( + 'Lenovo Chromebook Laptop (2023), 14" FHD Touchscreen Slim 3, + 8-Core MediaTek Kompanio 520 CPU, 4GB RAM, 128GB Storage', + 'German', // optional language + 400, // optional quantity + 'optional neutral voice tone', // optional voice tone + 'optional current e-store categories' // optional context, current categories to match + ); $resultSharpApiJob = $sharpApi->fetchResults($statusUrl); @@ -119,10 +126,15 @@ use GuzzleHttp\Exception\ClientException; // Step 1: dispatch the job to the API with one of the methods, for example: try { - $statusUrl = \SharpApiService::summarizeText($text, 'German'); + $statusUrl = \SharpApiService::summarizeText( + $text, + 'German' // optional language + 500, // optional length + 'neutral' // optional voice tone + ); // $statusUrl example value: 'https://sharpapi.com/api/v1/job/status/75acb6dc-a975-4969-9ef1-c62cebc511cb' } catch (ClientException $e) { - // $e->getResponse() + $e->getResponse() } // Step 2: request to check job status in polling mode and wait for the result @@ -181,7 +193,7 @@ class SharpTest extends Controller } ``` -## List of API methods/endpoints +## 📋 List of API methods/endpoints Each method always returns `SharpApiJob` object, where its `getResultJson / getResultArray / getResultObject` @@ -191,10 +203,11 @@ at [SharpAPI.com](https://sharpapi.com/). For methods that have language parameter you can also use `SharpApiLanguages` Enum values to make your code more readable. +--- -### HR +### 🧑‍💻 HR -#### Parse Resume/CV File +#### ⭐ Parse Resume/CV File Parses a resume (CV) file from multiple formats (PDF/DOC/DOCX/TXT/RTF) and returns an extensive object of data points. @@ -204,7 +217,7 @@ An optional output language parameter can also be provided (`English` value is s $statusUrl = \SharpApiService::parseResume('/test/resume.pdf', 'English'); ``` -#### Generate Job Description +#### ⭐ Generate Job Description Based on the list of extensive parameters this endpoint provides concise job details in the response format, including the short description, job requirements, and job responsibilities. @@ -214,96 +227,218 @@ This functionality utilizes a specialized `DTO` class (`Data Transfer Object`) p named `JobDescriptionParameters` to aid in the validation of input parameters. Only the `name` parameter in the constructor of this `DTO` is mandatory. +You can set your preferred writing style by providing a voice_tone parameter. +It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. + +This API method also provides an optional context parameter, which can be used +to supply additional flexible instructions for content processing. + ```php $jobDescriptionParameters = new JobDescriptionParameters( name: "PHP Senior Engineer", - company_name: "ACME LTD", - minimum_work_experience: "5 years", - minimum_education: "Bachelor Degree", - employment_type: "full time", - required_skills: ['PHP8', 'Laravel'], - optional_skills: ['AWS', 'Redis'], - country: "United Kingdom", - remote: true, - visa_sponsored: true, - language: 'English' + company_name: "ACME LTD", // optional + minimum_work_experience: "5 years", // optional + minimum_education: "Bachelor Degree", // optional + employment_type: "full time", // optional + required_skills: ['PHP8', 'Laravel'], // optional + optional_skills: ['AWS', 'Redis'], // optional + country: "United Kingdom", // optional + remote: true, // optional + visa_sponsored: true, // optional + voice_tone: 'Professional and Geeky', // optional voice tone + context: null, // optional context, additional AI processing instructions + language: null // optional output language ); $statusUrl = \SharpApiService::generateJobDescription($jobDescriptionParameters); ``` -#### Related Skills +#### ⭐ Related Skills Generates a list of related skills with their weights as a float value (1.0-10.0) where 10 equals 100%, the highest relevance score. +Only first parameter (`name`) is required. + +You can limit the output with the `max_quantity` parameter. + ```php -$statusUrl = \SharpApiService::relatedSkills('MySQL', 'English'); +$statusUrl = \SharpApiService::relatedSkills( + 'MySQL', + 'English', // optional language + 10 // optional quantity + ); ``` -#### Related Job Positions +#### ⭐ Related Job Positions Generates a list of related job positions with their weights as float value (1.0-10.0) where 10 equals 100%, the highest relevance score. +Only first parameter (`name`) is required. + +You can limit the output with the `max_quantity` parameter. + ```php -$statusUrl = \SharpApiService::relatedJobPositions('Senior PHP Engineer', 'English'); +$statusUrl = \SharpApiService::relatedJobPositions( + 'Senior PHP Engineer', + 'English', // optional language + 10 // optional quantity + ); ``` -### E-commerce +--- + + +### 🛒 E-commerce -#### Product Review Sentiment +#### ⭐ Product Review Sentiment Parses the customer's product review and provides its sentiment (POSITIVE/NEGATIVE/NEUTRAL) with a score between 0-100%. Great for sentiment report processing for any online store. ```php -$statusUrl = \SharpApiService::productReviewSentiment('review contents'); +$statusUrl = \SharpApiService::productReviewSentiment('customer review contents'); ``` -#### Product Categories +#### ⭐ Product Categories Generates a list of suitable categories for the product with relevance weights as a float value (1.0-10.0) where 10 equals 100%, the highest relevance score. Provide the product name and its parameters to get the best category matches possible. Comes in handy with populating product catalogue data and bulk products' processing. +You can limit the output with the `max_quantity` parameter. + +You can set your preferred writing style by providing a `voice_tone` parameter. +It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. + +Within an additional optional parameter context, you can provide a list of other categories +that will be taken into consideration during the mapping process +(for example your current e-commerce categories). + + ```php -$statusUrl = \SharpApiService::productCategories('Sony Playstation 5', 'English'); +$statusUrl = \SharpApiService::productCategories( + 'Sony Playstation 5', + 'English', // optional language + 5, // optional quantity + 'Tech-savvy', // optional voice tone + 'Game Console, PS5 Console' // optional context, current categories to match + ); ``` -#### Generate Product Intro +#### ⭐ Generate Product Intro Generates a shorter version of the product description. Provide as many details and parameters of the product to get the best marketing introduction possible. Comes in handy with populating product catalog data and bulk products processing. +You can limit the output with the `max_length` parameter. Please keep in mind that `max_length` serves as a strong +suggestion for the Language Model, rather than a strict requirement, to maintain the general sense of the outcome. + +You can set your preferred writing style by providing a `voice_tone` parameter. +It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. + ```php -$statusUrl = \SharpApiService::generateProductIntro('Sony Playstation 5', 'English'); +$statusUrl = \SharpApiService::generateProductIntro( + 'Sony Playstation 5', + SharpApiLanguages::ENGLISH, // optional language + 300, // optional length + 'Funny' // optional voice tone + ); ``` -#### Generate Thank You E-mail +#### ⭐ Generate Thank You E-mail Generates a personalized thank-you email to the customer after the purchase. The response content does not contain the title, greeting or sender info at the end, so you can personalize the rest of the email easily. +You can limit the output with the max_length parameter. Please keep in mind that `max_length` serves +as a strong suggestion for the Language Model, rather than a strict requirement, +to maintain the general sense of the outcome. + +You can set your preferred writing style by providing a `voice_tone` parameter. +It can be adjectives like funny or joyous, or even the name of a famous writer. + +This API method also provides an optional context parameter, which can be used to supply additional +flexible instructions for content processing. + ```php -$statusUrl = \SharpApiService::generateThankYouEmail('Sony Playstation 5', 'English'); +$statusUrl = \SharpApiService::generateThankYouEmail( + 'Sony Playstation 5', + SharpApiLanguages::ENGLISH, // optional language + 250, // optional length + 'Neutral', // optional voice tone + 'Must invite customer to visit again before Holidays' // optional context + ); ``` -### Content +--- + -#### Translate Text +### 📝️ Content + +#### ⭐ Translate Text Translates provided text to selected language. 80 languages are supported. Please check included `SharpApiLanguages` _Enum_ class for details. +You can set your preferred writing style by providing a `voice_tone` parameter. +It can be adjectives like funny or joyous, or even the name of a famous writer. + +An optional `context` parameter is also available. It can be used to provide more context to the translated text, +like the use case example or some additional explanations. + ```php -$statusUrl = \SharpApiService::translate($text, SharpApiLanguages::ITALIAN); +$statusUrl = \SharpApiService::translate( + 'turn', + SharpApiLanguages::FRENCH, // optional language + 'neutral', // optional voice tone + 'to turn a page' // optional context + ); + +// will result in : +// {"content": "tourner", "to_language": "French", "from_language": "English"} ``` -#### Detect Spam +#### ⭐ Paraphrase / Rephrase + +Generates a paraphrased version of the provided text. +Only the `content` parameter is required. You can define the output language, +maximum character length, and tone of voice. + +Additional instructions on how to process the text can be provided in the context parameter. +Please keep in mind that `max_length` serves as a strong suggestion +for the Language Model, rather than a strict requirement, +to maintain the general sense of the outcome. + +You can set your preferred writing style by providing an optional `voice_tone` parameter. +It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. + +This API method also provides an optional `context` parameter, +which can be used to supply additional flexible instructions for content processing. + +```php +$statusUrl = \SharpApiService::paraphrase( + $text, + SharpApiLanguages::FRENCH, // optional language + 500, // optional length + 'neutral', // optional voice tone + 'avoid using abbreviations' // optional context + ); +``` + +#### ⭐ Proofread Text + Grammar Check + +Proofreads (and checks grammar) a provided text. + +```php +$statusUrl = \SharpApiService::proofread($text); +``` + +#### ⭐ Detect Spam Checks if provided content passes a spam filtration test. Provides a percentage confidence score and an explanation @@ -314,7 +449,7 @@ This information is useful for moderators to make a final decision. $statusUrl = \SharpApiService::detectSpam($text); ``` -#### Detect Phones Numbers +#### ⭐ Detect Phones Numbers Parses the provided text for any phone numbers and returns the original detected version and its E.164 format. Might come in handy in the case of processing @@ -325,7 +460,7 @@ to detect phone numbers in places where they're not supposed to be. $statusUrl = \SharpApiService::detectPhones($text); ``` -#### Detect Emails +#### ⭐ Detect Emails Parses the provided text for any possible emails. Might come in handy in case of processing and validating big chunks of data against email addresses @@ -335,38 +470,70 @@ or f.e. if you want to detect emails in places where they're not supposed to be. $statusUrl = \SharpApiService::detectEmails($text); ``` -#### Generate Keywords/Tags +#### ⭐ Generate Keywords/Tags Generates a list of unique keywords/tags based on the provided content. +You can limit the output with the `max_quantity` parameter. + +You can set your preferred writing style by providing a `voice_tone` parameter. + ```php -$statusUrl = \SharpApiService::generateKeywords($text, 'English'); +$statusUrl = \SharpApiService::generateKeywords( + $text, + 'English', // optional language + 5, // optional length + 'Freaky & Curious' // optional voice tone + ); ``` - -#### Summarize Text +#### ⭐ Summarize Text Generates a summarized version of the provided content. Perfect for generating marketing introductions of longer texts. +You can limit the output with the `max_length` parameter. +Please keep in mind that `max_length` serves as a strong suggestion for the Language Model, +rather than a strict requirement, to maintain the general sense of the outcome. + +You can set your preferred writing style by providing a `voice_ton`e parameter. +It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. + ```php -$statusUrl = \SharpApiService::summarizeText($text, 'English'); +$statusUrl = \SharpApiService::summarizeText( + $text, + 'English', // optional language + 'David Attenborough' // optional voice tone + ); ``` -### SEO +--- -#### Generate SEO Tags + +### 🗒 SEO + +#### ⭐ Generate SEO Tags Generates all most important META tags based on the content provided. Make sure to include link to the website and pictures URL to get as many tags populated as possible. +You can set your preferred writing style by providing a `voice_ton`e parameter. +It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. + ```php -$statusUrl = \SharpApiService::generateSeoTags($text, 'English'); +$statusUrl = \SharpApiService::generateSeoTags( + $text, + 'English', // optional language + 'David Attenborough' // optional voice tone + ); ``` -### Travel, Tourism & Hospitality +--- + + +### ✈️ Travel, Tourism & Hospitality -#### Travel Review Sentiment +#### ⭐ Travel Review Sentiment Parses the Travel/Hospitality product review and provides its sentiment (POSITIVE/NEGATIVE/NEUTRAL) with a score between 0-100%. @@ -376,7 +543,7 @@ Great for sentiment report processing for any online store. $statusUrl = \SharpApiService::travelReviewSentiment($text); ``` -#### Tours & Activities Product Categories +#### ⭐ Tours & Activities Product Categories Generates a list of suitable categories for the Tours & Activities product with relevance weights as float value (1.0-10.0) where 10 equals 100%, @@ -385,16 +552,29 @@ to get the best category matches possible. Comes in handy with populating product catalogue data and bulk product processing. Only first parameter `productName` is required. +You can limit the output with the `max_quantity` parameter. + +You can set your preferred writing style by providing a `voice_tone` parameter. +It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. + +Within an additional optional parameter `context`, you can provide a list of other categories +that will be taken into consideration during the mapping process +(for example your current e-commerce categories). + + ```php $statusUrl = \SharpApiService::toursAndActivitiesProductCategories( 'Oasis of the Bay' - 'Ha Long', - 'Vietnam', - 'English' + 'Ha Long', // optional city + 'Vietnam', // optional country + 'English', // optional language + 10, // optional quantity + 'Adventurous', // optional voice tone + 'Bay Hotels, Ha Long Hotels' // optional context, current categories to match ); ``` -#### Hospitality Product Categories +#### ⭐ Hospitality Product Categories Generates a list of suitable categories for the Hospitality type product with relevance weights as float value (1.0-10.0) where 10 equals 100%, @@ -403,15 +583,79 @@ to get the best category matches possible. Comes in handy with populating products catalogs data and bulk products' processing. Only first parameter `productName` is required. +You can limit the output with the `max_quantity` parameter. + +You can set your preferred writing style by providing a `voice_tone` parameter. +It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. + +Within an additional optional parameter `context`, you can provide a list of other categories +that will be taken into consideration during the mapping process +(for example your current e-commerce categories). + ```php $statusUrl = \SharpApiService::hospitalityProductCategories( 'Hotel Crystal 大人専用' - 'Tokyo', - 'Japan', - 'English' + 'Tokyo', // optional city + 'Japan', // optional country + 'English', // optional language + 10, // optional quantity + 'Adventurous', // optional voice tone + 'Tokyo Hotels, Crystal Hotels' // optional context, current categories to match ); ``` +--- + +### 🤖 Technical API Endpoints + +#### ⭐ Subscription information / quota check +Endpoint to check details regarding the subscription's current period + +```php +$statusUrl = \SharpApiService::quota(); +``` + +will result in: +```json +{ + "timestamp": "2024-03-19T12:49:41.445736Z", + "on_trial": false, + "trial_ends": "2024-03-17T07:57:46.000000Z", + "subscribed": true, + "current_subscription_start": "2024-03-18T12:37:39.000000Z", + "current_subscription_end": "2024-04-18T12:37:39.000000Z", + "subscription_words_quota": 100000, + "subscription_words_used": 9608, + "subscription_words_used_percentage": 0.1 +} +``` + +`subscription_words_used_percentage` is a percentage of current monthly quota usage +and might serve as an alert to the user of the depleted credits. +With a value above 80%, it's advised to subscribe to more credits +at https://sharpapi.com/dashboard/credits to avoid service disruption. + +These values are also available in the Dashboard at https://sharpapi.com/dashboard + +#### ⭐ Ping + +Simple PING endpoint to check the availability of the API and it's internal timze zone (timestamp). + +```php +$statusUrl = \SharpApiService::ping(); +``` + +will result in: +```json +{ + "ping": "pong", + "timestamp": "2024-03-12T08:50:11.188308Z" +} +``` + +--- + + ### Do you think our API is missing some obvious functionality? [Please let us know»](https://github.com/sharpapi/sharpapi-php-client/issues) diff --git a/composer.json b/composer.json index e15eeed..a26ef36 100644 --- a/composer.json +++ b/composer.json @@ -1,14 +1,27 @@ { "name": "sharpapi/sharpapi-php-client", - "description": "SharpAPI - AI-Powered Swiss Army Knife API. Assisting coders with the most repetitive content analysis and content generation processing needs of any app or platform.", + "description": "SharpAPI.com - AI-Powered Swiss Army Knife API. Save countless coding hours and supercharge your app with AI capabilities in just 2 lines of code.", "keywords": [ - "SharpAPI", - "API", - "AI API", - "automation", - "API Integration", - "Content Processing", - "App Enhancement" + "sharpapi", + "ai-powered", + "ai capabilities", + "api", + "ai api", + "api integration", + "artificial intelligence", + "natural language processing", + "restful api", + "php", + "software development", + "content generation", + "content analysis", + "e-commerce", + "hr tech", + "travel", + "tourism", + "hospitality", + "marketing automation", + "api integration" ], "homepage": "https://github.com/sharpapi/sharpapi-php-client", "license": "MIT", @@ -22,7 +35,8 @@ "require": { "php": "^8.1", "guzzlehttp/guzzle": "^7.8", - "kongulov/interact-with-enum": "^1.0" + "kongulov/interact-with-enum": "^1.0", + "nesbot/carbon": "^3.0" }, "autoload": { "psr-4": { diff --git a/composer.lock b/composer.lock deleted file mode 100644 index caf3da5..0000000 --- a/composer.lock +++ /dev/null @@ -1,663 +0,0 @@ -{ - "_readme": [ - "This file locks the dependencies of your project to a known state", - "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", - "This file is @generated automatically" - ], - "content-hash": "710b087649bcd20ae2e09ae997653ee3", - "packages": [ - { - "name": "guzzlehttp/guzzle", - "version": "7.8.1", - "source": { - "type": "git", - "url": "https://github.com/guzzle/guzzle.git", - "reference": "41042bc7ab002487b876a0683fc8dce04ddce104" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/guzzle/guzzle/zipball/41042bc7ab002487b876a0683fc8dce04ddce104", - "reference": "41042bc7ab002487b876a0683fc8dce04ddce104", - "shasum": "" - }, - "require": { - "ext-json": "*", - "guzzlehttp/promises": "^1.5.3 || ^2.0.1", - "guzzlehttp/psr7": "^1.9.1 || ^2.5.1", - "php": "^7.2.5 || ^8.0", - "psr/http-client": "^1.0", - "symfony/deprecation-contracts": "^2.2 || ^3.0" - }, - "provide": { - "psr/http-client-implementation": "1.0" - }, - "require-dev": { - "bamarni/composer-bin-plugin": "^1.8.2", - "ext-curl": "*", - "php-http/client-integration-tests": "dev-master#2c025848417c1135031fdf9c728ee53d0a7ceaee as 3.0.999", - "php-http/message-factory": "^1.1", - "phpunit/phpunit": "^8.5.36 || ^9.6.15", - "psr/log": "^1.1 || ^2.0 || ^3.0" - }, - "suggest": { - "ext-curl": "Required for CURL handler support", - "ext-intl": "Required for Internationalized Domain Name (IDN) support", - "psr/log": "Required for using the Log middleware" - }, - "type": "library", - "extra": { - "bamarni-bin": { - "bin-links": true, - "forward-command": false - } - }, - "autoload": { - "files": [ - "src/functions_include.php" - ], - "psr-4": { - "GuzzleHttp\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Graham Campbell", - "email": "hello@gjcampbell.co.uk", - "homepage": "https://github.com/GrahamCampbell" - }, - { - "name": "Michael Dowling", - "email": "mtdowling@gmail.com", - "homepage": "https://github.com/mtdowling" - }, - { - "name": "Jeremy Lindblom", - "email": "jeremeamia@gmail.com", - "homepage": "https://github.com/jeremeamia" - }, - { - "name": "George Mponos", - "email": "gmponos@gmail.com", - "homepage": "https://github.com/gmponos" - }, - { - "name": "Tobias Nyholm", - "email": "tobias.nyholm@gmail.com", - "homepage": "https://github.com/Nyholm" - }, - { - "name": "Márk Sági-Kazár", - "email": "mark.sagikazar@gmail.com", - "homepage": "https://github.com/sagikazarmark" - }, - { - "name": "Tobias Schultze", - "email": "webmaster@tubo-world.de", - "homepage": "https://github.com/Tobion" - } - ], - "description": "Guzzle is a PHP HTTP client library", - "keywords": [ - "client", - "curl", - "framework", - "http", - "http client", - "psr-18", - "psr-7", - "rest", - "web service" - ], - "support": { - "issues": "https://github.com/guzzle/guzzle/issues", - "source": "https://github.com/guzzle/guzzle/tree/7.8.1" - }, - "funding": [ - { - "url": "https://github.com/GrahamCampbell", - "type": "github" - }, - { - "url": "https://github.com/Nyholm", - "type": "github" - }, - { - "url": "https://tidelift.com/funding/github/packagist/guzzlehttp/guzzle", - "type": "tidelift" - } - ], - "time": "2023-12-03T20:35:24+00:00" - }, - { - "name": "guzzlehttp/promises", - "version": "2.0.2", - "source": { - "type": "git", - "url": "https://github.com/guzzle/promises.git", - "reference": "bbff78d96034045e58e13dedd6ad91b5d1253223" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/guzzle/promises/zipball/bbff78d96034045e58e13dedd6ad91b5d1253223", - "reference": "bbff78d96034045e58e13dedd6ad91b5d1253223", - "shasum": "" - }, - "require": { - "php": "^7.2.5 || ^8.0" - }, - "require-dev": { - "bamarni/composer-bin-plugin": "^1.8.2", - "phpunit/phpunit": "^8.5.36 || ^9.6.15" - }, - "type": "library", - "extra": { - "bamarni-bin": { - "bin-links": true, - "forward-command": false - } - }, - "autoload": { - "psr-4": { - "GuzzleHttp\\Promise\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Graham Campbell", - "email": "hello@gjcampbell.co.uk", - "homepage": "https://github.com/GrahamCampbell" - }, - { - "name": "Michael Dowling", - "email": "mtdowling@gmail.com", - "homepage": "https://github.com/mtdowling" - }, - { - "name": "Tobias Nyholm", - "email": "tobias.nyholm@gmail.com", - "homepage": "https://github.com/Nyholm" - }, - { - "name": "Tobias Schultze", - "email": "webmaster@tubo-world.de", - "homepage": "https://github.com/Tobion" - } - ], - "description": "Guzzle promises library", - "keywords": [ - "promise" - ], - "support": { - "issues": "https://github.com/guzzle/promises/issues", - "source": "https://github.com/guzzle/promises/tree/2.0.2" - }, - "funding": [ - { - "url": "https://github.com/GrahamCampbell", - "type": "github" - }, - { - "url": "https://github.com/Nyholm", - "type": "github" - }, - { - "url": "https://tidelift.com/funding/github/packagist/guzzlehttp/promises", - "type": "tidelift" - } - ], - "time": "2023-12-03T20:19:20+00:00" - }, - { - "name": "guzzlehttp/psr7", - "version": "2.6.2", - "source": { - "type": "git", - "url": "https://github.com/guzzle/psr7.git", - "reference": "45b30f99ac27b5ca93cb4831afe16285f57b8221" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/guzzle/psr7/zipball/45b30f99ac27b5ca93cb4831afe16285f57b8221", - "reference": "45b30f99ac27b5ca93cb4831afe16285f57b8221", - "shasum": "" - }, - "require": { - "php": "^7.2.5 || ^8.0", - "psr/http-factory": "^1.0", - "psr/http-message": "^1.1 || ^2.0", - "ralouphie/getallheaders": "^3.0" - }, - "provide": { - "psr/http-factory-implementation": "1.0", - "psr/http-message-implementation": "1.0" - }, - "require-dev": { - "bamarni/composer-bin-plugin": "^1.8.2", - "http-interop/http-factory-tests": "^0.9", - "phpunit/phpunit": "^8.5.36 || ^9.6.15" - }, - "suggest": { - "laminas/laminas-httphandlerrunner": "Emit PSR-7 responses" - }, - "type": "library", - "extra": { - "bamarni-bin": { - "bin-links": true, - "forward-command": false - } - }, - "autoload": { - "psr-4": { - "GuzzleHttp\\Psr7\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Graham Campbell", - "email": "hello@gjcampbell.co.uk", - "homepage": "https://github.com/GrahamCampbell" - }, - { - "name": "Michael Dowling", - "email": "mtdowling@gmail.com", - "homepage": "https://github.com/mtdowling" - }, - { - "name": "George Mponos", - "email": "gmponos@gmail.com", - "homepage": "https://github.com/gmponos" - }, - { - "name": "Tobias Nyholm", - "email": "tobias.nyholm@gmail.com", - "homepage": "https://github.com/Nyholm" - }, - { - "name": "Márk Sági-Kazár", - "email": "mark.sagikazar@gmail.com", - "homepage": "https://github.com/sagikazarmark" - }, - { - "name": "Tobias Schultze", - "email": "webmaster@tubo-world.de", - "homepage": "https://github.com/Tobion" - }, - { - "name": "Márk Sági-Kazár", - "email": "mark.sagikazar@gmail.com", - "homepage": "https://sagikazarmark.hu" - } - ], - "description": "PSR-7 message implementation that also provides common utility methods", - "keywords": [ - "http", - "message", - "psr-7", - "request", - "response", - "stream", - "uri", - "url" - ], - "support": { - "issues": "https://github.com/guzzle/psr7/issues", - "source": "https://github.com/guzzle/psr7/tree/2.6.2" - }, - "funding": [ - { - "url": "https://github.com/GrahamCampbell", - "type": "github" - }, - { - "url": "https://github.com/Nyholm", - "type": "github" - }, - { - "url": "https://tidelift.com/funding/github/packagist/guzzlehttp/psr7", - "type": "tidelift" - } - ], - "time": "2023-12-03T20:05:35+00:00" - }, - { - "name": "kongulov/interact-with-enum", - "version": "1.0.0", - "source": { - "type": "git", - "url": "https://github.com/kongulov/interact-with-enum.git", - "reference": "89acf4725e0408a7c1945d239fdf519eb1076224" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/kongulov/interact-with-enum/zipball/89acf4725e0408a7c1945d239fdf519eb1076224", - "reference": "89acf4725e0408a7c1945d239fdf519eb1076224", - "shasum": "" - }, - "require": { - "php": "^8.1" - }, - "type": "library", - "autoload": { - "psr-4": { - "Kongulov\\Traits\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Ramiz Kongulov", - "email": "ramiz.kongulov@gmail.com", - "role": "Developer" - } - ], - "description": "Trait for convenient use of ENUM in PHP", - "homepage": "https://github.com/kongulov/interact-with-enum", - "keywords": [ - "enum", - "php" - ], - "support": { - "issues": "https://github.com/kongulov/interact-with-enum/issues", - "source": "https://github.com/kongulov/interact-with-enum/tree/1.0.0" - }, - "time": "2023-06-28T19:30:17+00:00" - }, - { - "name": "psr/http-client", - "version": "1.0.3", - "source": { - "type": "git", - "url": "https://github.com/php-fig/http-client.git", - "reference": "bb5906edc1c324c9a05aa0873d40117941e5fa90" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/php-fig/http-client/zipball/bb5906edc1c324c9a05aa0873d40117941e5fa90", - "reference": "bb5906edc1c324c9a05aa0873d40117941e5fa90", - "shasum": "" - }, - "require": { - "php": "^7.0 || ^8.0", - "psr/http-message": "^1.0 || ^2.0" - }, - "type": "library", - "extra": { - "branch-alias": { - "dev-master": "1.0.x-dev" - } - }, - "autoload": { - "psr-4": { - "Psr\\Http\\Client\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "PHP-FIG", - "homepage": "https://www.php-fig.org/" - } - ], - "description": "Common interface for HTTP clients", - "homepage": "https://github.com/php-fig/http-client", - "keywords": [ - "http", - "http-client", - "psr", - "psr-18" - ], - "support": { - "source": "https://github.com/php-fig/http-client" - }, - "time": "2023-09-23T14:17:50+00:00" - }, - { - "name": "psr/http-factory", - "version": "1.0.2", - "source": { - "type": "git", - "url": "https://github.com/php-fig/http-factory.git", - "reference": "e616d01114759c4c489f93b099585439f795fe35" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/php-fig/http-factory/zipball/e616d01114759c4c489f93b099585439f795fe35", - "reference": "e616d01114759c4c489f93b099585439f795fe35", - "shasum": "" - }, - "require": { - "php": ">=7.0.0", - "psr/http-message": "^1.0 || ^2.0" - }, - "type": "library", - "extra": { - "branch-alias": { - "dev-master": "1.0.x-dev" - } - }, - "autoload": { - "psr-4": { - "Psr\\Http\\Message\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "PHP-FIG", - "homepage": "https://www.php-fig.org/" - } - ], - "description": "Common interfaces for PSR-7 HTTP message factories", - "keywords": [ - "factory", - "http", - "message", - "psr", - "psr-17", - "psr-7", - "request", - "response" - ], - "support": { - "source": "https://github.com/php-fig/http-factory/tree/1.0.2" - }, - "time": "2023-04-10T20:10:41+00:00" - }, - { - "name": "psr/http-message", - "version": "2.0", - "source": { - "type": "git", - "url": "https://github.com/php-fig/http-message.git", - "reference": "402d35bcb92c70c026d1a6a9883f06b2ead23d71" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/php-fig/http-message/zipball/402d35bcb92c70c026d1a6a9883f06b2ead23d71", - "reference": "402d35bcb92c70c026d1a6a9883f06b2ead23d71", - "shasum": "" - }, - "require": { - "php": "^7.2 || ^8.0" - }, - "type": "library", - "extra": { - "branch-alias": { - "dev-master": "2.0.x-dev" - } - }, - "autoload": { - "psr-4": { - "Psr\\Http\\Message\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "PHP-FIG", - "homepage": "https://www.php-fig.org/" - } - ], - "description": "Common interface for HTTP messages", - "homepage": "https://github.com/php-fig/http-message", - "keywords": [ - "http", - "http-message", - "psr", - "psr-7", - "request", - "response" - ], - "support": { - "source": "https://github.com/php-fig/http-message/tree/2.0" - }, - "time": "2023-04-04T09:54:51+00:00" - }, - { - "name": "ralouphie/getallheaders", - "version": "3.0.3", - "source": { - "type": "git", - "url": "https://github.com/ralouphie/getallheaders.git", - "reference": "120b605dfeb996808c31b6477290a714d356e822" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/ralouphie/getallheaders/zipball/120b605dfeb996808c31b6477290a714d356e822", - "reference": "120b605dfeb996808c31b6477290a714d356e822", - "shasum": "" - }, - "require": { - "php": ">=5.6" - }, - "require-dev": { - "php-coveralls/php-coveralls": "^2.1", - "phpunit/phpunit": "^5 || ^6.5" - }, - "type": "library", - "autoload": { - "files": [ - "src/getallheaders.php" - ] - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Ralph Khattar", - "email": "ralph.khattar@gmail.com" - } - ], - "description": "A polyfill for getallheaders.", - "support": { - "issues": "https://github.com/ralouphie/getallheaders/issues", - "source": "https://github.com/ralouphie/getallheaders/tree/develop" - }, - "time": "2019-03-08T08:55:37+00:00" - }, - { - "name": "symfony/deprecation-contracts", - "version": "v3.4.0", - "source": { - "type": "git", - "url": "https://github.com/symfony/deprecation-contracts.git", - "reference": "7c3aff79d10325257a001fcf92d991f24fc967cf" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/symfony/deprecation-contracts/zipball/7c3aff79d10325257a001fcf92d991f24fc967cf", - "reference": "7c3aff79d10325257a001fcf92d991f24fc967cf", - "shasum": "" - }, - "require": { - "php": ">=8.1" - }, - "type": "library", - "extra": { - "branch-alias": { - "dev-main": "3.4-dev" - }, - "thanks": { - "name": "symfony/contracts", - "url": "https://github.com/symfony/contracts" - } - }, - "autoload": { - "files": [ - "function.php" - ] - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Nicolas Grekas", - "email": "p@tchwork.com" - }, - { - "name": "Symfony Community", - "homepage": "https://symfony.com/contributors" - } - ], - "description": "A generic function and convention to trigger deprecation notices", - "homepage": "https://symfony.com", - "support": { - "source": "https://github.com/symfony/deprecation-contracts/tree/v3.4.0" - }, - "funding": [ - { - "url": "https://symfony.com/sponsor", - "type": "custom" - }, - { - "url": "https://github.com/fabpot", - "type": "github" - }, - { - "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", - "type": "tidelift" - } - ], - "time": "2023-05-23T14:45:45+00:00" - } - ], - "packages-dev": [], - "aliases": [], - "minimum-stability": "dev", - "stability-flags": [], - "prefer-stable": true, - "prefer-lowest": false, - "platform": { - "php": "^8.0" - }, - "platform-dev": [], - "plugin-api-version": "2.6.0" -} diff --git a/src/Dto/JobDescriptionParameters.php b/src/Dto/JobDescriptionParameters.php index dde7b0f..b5a5826 100644 --- a/src/Dto/JobDescriptionParameters.php +++ b/src/Dto/JobDescriptionParameters.php @@ -9,16 +9,18 @@ class JobDescriptionParameters { public function __construct( public string $name, - public ?string $company_name, - public ?string $minimum_work_experience, - public ?string $minimum_education, - public ?string $employment_type, - public ?array $required_skills, - public ?array $optional_skills, - public ?string $country, - public ?bool $remote, - public ?bool $visa_sponsored, - public ?string $language = 'English', + public ?string $company_name = null, + public ?string $minimum_work_experience = null, + public ?string $minimum_education = null, + public ?string $employment_type = null, + public ?array $required_skills = null, + public ?array $optional_skills = null, + public ?string $country = null, + public ?bool $remote = null, + public ?bool $visa_sponsored = null, + public ?string $voice_tone = null, + public ?string $context = null, + public ?string $language = null, ) { } @@ -35,6 +37,8 @@ public function toArray(): array 'country' => $this->country, 'remote' => $this->remote, 'visa_sponsored' => $this->visa_sponsored, + 'voice_tone' => $this->voice_tone, + 'context' => $this->context, 'language' => $this->language, ]; } diff --git a/src/Dto/SharpApiSubscriptionInfo.php b/src/Dto/SharpApiSubscriptionInfo.php new file mode 100644 index 0000000..61d0809 --- /dev/null +++ b/src/Dto/SharpApiSubscriptionInfo.php @@ -0,0 +1,54 @@ + $this->timestamp, + 'on_trial' => $this->on_trial, + 'trial_ends' => $this->trial_ends, + 'subscribed' => $this->subscribed, + 'current_subscription_start' => $this->current_subscription_start, + 'current_subscription_end' => $this->current_subscription_end, + 'subscription_words_quota' => $this->subscription_words_quota, + 'subscription_words_used' => $this->subscription_words_used, + 'subscription_words_used_percentage' => $this->subscription_words_used_percentage, + ]; + } +} diff --git a/src/Enums/SharpApiJobTypeEnum.php b/src/Enums/SharpApiJobTypeEnum.php index f5d2c3d..ed93196 100644 --- a/src/Enums/SharpApiJobTypeEnum.php +++ b/src/Enums/SharpApiJobTypeEnum.php @@ -27,8 +27,36 @@ enum SharpApiJobTypeEnum: string case CONTENT_SUMMARIZE = 'content_summarize'; case CONTENT_KEYWORDS = 'content_keywords'; case CONTENT_TRANSLATE = 'content_translate'; + case CONTENT_PARAPHRASE = 'content_paraphrase'; + case CONTENT_PROOFREAD = 'content_proofread'; case SEO_GENERATE_TAGS = 'seo_generate_tags'; + public function url(): string + { + return match ($this) { + self::ECOMMERCE_REVIEW_SENTIMENT => '/ecommerce/review_sentiment', + self::ECOMMERCE_PRODUCT_CATEGORIES => '/ecommerce/product_categories', + self::ECOMMERCE_PRODUCT_INTRO => '/ecommerce/product_intro', + self::ECOMMERCE_THANK_YOU_EMAIL => '/ecommerce/thank_you_email', + self::HR_PARSE_RESUME => '/hr/parse_resume', + self::HR_JOB_DESCRIPTION => '/hr/job_description', + self::HR_RELATED_SKILLS => '/hr/related_skills', + self::HR_RELATED_JOB_POSITIONS => '/hr/related_job_positions', + self::TTH_REVIEW_SENTIMENT => '/tth/review_sentiment', + self::TTH_TA_PRODUCT_CATEGORIES => '/tth/ta_product_categories', + self::TTH_HOSPITALITY_PRODUCT_CATEGORIES => '/tth/hospitality_product_categories', + self::CONTENT_DETECT_PHONES => '/content/detect_phones', + self::CONTENT_DETECT_EMAILS => '/content/detect_emails', + self::CONTENT_DETECT_SPAM => '/content/detect_spam', + self::CONTENT_SUMMARIZE => '/content/summarize', + self::CONTENT_KEYWORDS => '/content/keywords', + self::CONTENT_TRANSLATE => '/content/translate', + self::CONTENT_PARAPHRASE => '/content/paraphrase', + self::CONTENT_PROOFREAD => '/content/proofread', + self::SEO_GENERATE_TAGS => '/seo/generate_tags', + }; + } + public function label(): string { return match ($this) { @@ -49,6 +77,8 @@ public function label(): string self::CONTENT_SUMMARIZE => 'Summarize Content', self::CONTENT_KEYWORDS => 'Generate Keywords/Tags', self::CONTENT_TRANSLATE => 'Translate Text', + self::CONTENT_PARAPHRASE => 'Paraphrase Text', + self::CONTENT_PROOFREAD => 'Proofread & Grammar check', self::SEO_GENERATE_TAGS => 'Generate SEO Tags', }; } @@ -71,6 +101,8 @@ public function category(): string self::CONTENT_DETECT_EMAILS, self::CONTENT_DETECT_SPAM, self::CONTENT_TRANSLATE, + self::CONTENT_PARAPHRASE, + self::CONTENT_PROOFREAD, self::CONTENT_KEYWORDS, self::CONTENT_SUMMARIZE => 'Content', self::SEO_GENERATE_TAGS => 'SEO', diff --git a/src/Enums/SharpApiVoiceTone.php b/src/Enums/SharpApiVoiceTone.php new file mode 100644 index 0000000..943637d --- /dev/null +++ b/src/Enums/SharpApiVoiceTone.php @@ -0,0 +1,66 @@ +setApiBaseUrl('https://sharpapi.com/api/v1'); $this->setApiKey($apiKey); if (empty($this->apiKey)) { throw new InvalidArgumentException('API key is required.'); } + $this->setApiBaseUrl($apiBaseUrl ?? 'https://sharpapi.com/api/v1'); + $this->setUserAgent($userAgent ?? 'SharpAPIPHPAgent/1.1.0'); } /** @@ -76,11 +81,31 @@ public function setApiKey(string $apiKey): void $this->apiKey = $apiKey; } + public function getUserAgent(): string + { + return $this->userAgent; + } + + /** + * Handy method to set custom User-Agent header for Affiliate Program members. + * + * More at: https://sharpapi.com/affiliate_program + */ + public function setUserAgent(string $userAgent): void + { + $this->userAgent = $userAgent; + } + public function getApiJobStatusPollingInterval(): int { return $this->apiJobStatusPollingInterval; } + /** + * @param int $apiJobStatusPollingInterval + * @return void + * @api + */ public function setApiJobStatusPollingInterval(int $apiJobStatusPollingInterval): void { $this->apiJobStatusPollingInterval = $apiJobStatusPollingInterval; @@ -91,6 +116,11 @@ public function isUseCustomInterval(): bool return $this->useCustomInterval; } + /** + * @param bool $useCustomInterval + * @return void + * @api + */ public function setUseCustomInterval(bool $useCustomInterval): void { $this->useCustomInterval = $useCustomInterval; @@ -101,6 +131,11 @@ public function getApiJobStatusPollingWait(): int return $this->apiJobStatusPollingWait; } + /** + * @param int $apiJobStatusPollingWait + * @return void + * @api + */ public function setApiJobStatusPollingWait(int $apiJobStatusPollingWait): void { $this->apiJobStatusPollingWait = $apiJobStatusPollingWait; @@ -135,7 +170,7 @@ private function makeRequest( } } - return $client->request($method, $url, $options); + return $client->request($method, $this->getApiBaseUrl() . $url, $options); } private function parseStatusUrl(ResponseInterface $response) @@ -202,12 +237,65 @@ public function fetchResults(string $statusUrl): SharpApiJob private function getHeaders(): array { return [ - 'Authorization' => 'Bearer ' . $this->apiKey, + 'Authorization' => 'Bearer ' . $this->getApiKey(), 'Accept' => 'application/json', - 'User-Agent' => 'SharpAPIPHPAgent/1.0.0', + 'User-Agent' => $this->getUserAgent() ]; } + /** + * Simple PING endpoint to check the availability of the API and its internal time zone (timestamp). + * { + * "ping": "pong", + * "timestamp": "2024-03-12T08:50:11.188308Z" + * } + * + * @throws GuzzleException + * + * @api + */ + public function ping(): ?array + { + $response = $this->makeRequest('GET', '/ping'); + + return json_decode($response->getBody()->__toString(), true); + } + + /** + * Endpoint to check details regarding the subscription's current period + * + * "subscription_words_used_percentage" is a percentage of current monthly quota usage + * and might serve as an alert to the user of the depleted credits. + * With a value above 80%, it's advised to subscribe to more credits + * at https://sharpapi.com/dashboard/credits to avoid service disruption. + * + * These values are also available in the Dashboard at https://sharpapi.com/dashboard + * + * @throws GuzzleException + * + * @api + */ + public function quota(): ?SharpApiSubscriptionInfo + { + $response = $this->makeRequest('GET', '/quota'); + $info = json_decode($response->getBody()->__toString(), true); + if (!array_key_exists('timestamp', $info)) { + return null; + } + + return new SharpApiSubscriptionInfo( + timestamp: new Carbon($info['timestamp']), + on_trial: $info['on_trial'], + trial_ends: new Carbon($info['trial_ends']), + subscribed: $info['subscribed'], + current_subscription_start: new Carbon($info['current_subscription_start']), + current_subscription_end: new Carbon($info['current_subscription_end']), + subscription_words_quota: $info['subscription_words_quota'], + subscription_words_used: $info['subscription_words_used'], + subscription_words_used_percentage: $info['subscription_words_used_percentage'] + ); + } + /** * Parses a resume (CV) file from multiple formats (PDF/DOC/DOCX/TXT/RTF) * and returns an extensive JSON object of data points. @@ -215,20 +303,21 @@ private function getHeaders(): array * An optional language parameter can also be provided (`English` value is set as the default one) . * * @param string $filePath The path to the resume file. - * @param string $language The language of the resume file. Defaults to 'English'. + * @param string|null $language The language of the resume file. Defaults to 'English'. * @return string The parsed data or an error message. * - * @throws RequestException If there is an issue with the API request. * @throws GuzzleException * * @api */ - public function parseResume(string $filePath, string $language = 'English'): string + public function parseResume( + string $filePath, + ?string $language = null + ): string { - $url = $this->apiBaseUrl . '/hr/parse_resume'; $response = $this->makeRequest( 'POST', - $url, + SharpApiJobTypeEnum::HR_PARSE_RESUME->url(), ['language' => $language], $filePath ); @@ -250,8 +339,10 @@ public function parseResume(string $filePath, string $language = 'English'): str */ public function generateJobDescription(JobDescriptionParameters $jobDescriptionParameters): string { - $url = $this->apiBaseUrl . '/hr/job_description'; - $response = $this->makeRequest('POST', $url, $jobDescriptionParameters->toArray()); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::HR_JOB_DESCRIPTION->url(), + $jobDescriptionParameters->toArray()); return $this->parseStatusUrl($response); } @@ -264,13 +355,20 @@ public function generateJobDescription(JobDescriptionParameters $jobDescriptionP * * @api */ - public function relatedSkills(string $skillName, string $language = 'English'): string + public function relatedSkills( + string $skillName, + ?string $language = null, + ?int $maxQuantity = null + ): string { - $url = $this->apiBaseUrl . '/hr/related_skills'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $skillName, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::HR_RELATED_SKILLS->url(), + [ + 'content' => $skillName, + 'language' => $language, + 'max_quantity' => $maxQuantity, + ]); return $this->parseStatusUrl($response); } @@ -283,13 +381,20 @@ public function relatedSkills(string $skillName, string $language = 'English'): * * @api */ - public function relatedJobPositions(string $jobPositionName, string $language = 'English'): string + public function relatedJobPositions( + string $jobPositionName, + ?string $language = null, + ?int $maxQuantity = null + ): string { - $url = $this->apiBaseUrl . '/hr/related_job_positions'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $jobPositionName, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::HR_RELATED_JOB_POSITIONS->url(), + [ + 'content' => $jobPositionName, + 'language' => $language, + 'max_quantity' => $maxQuantity, + ]); return $this->parseStatusUrl($response); } @@ -304,10 +409,11 @@ public function relatedJobPositions(string $jobPositionName, string $language = */ public function productReviewSentiment(string $review): string { - $url = $this->apiBaseUrl . '/ecommerce/review_sentiment'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $review, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::ECOMMERCE_REVIEW_SENTIMENT->url(), + ['content' => $review] + ); return $this->parseStatusUrl($response); } @@ -322,13 +428,24 @@ public function productReviewSentiment(string $review): string * * @api */ - public function productCategories(string $productName, string $language = 'English'): string + public function productCategories( + string $productName, + ?string $language = null, + ?int $maxQuantity = null, + ?string $voiceTone = null, + ?string $context = null + ): string { - $url = $this->apiBaseUrl . '/ecommerce/product_categories'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $productName, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::ECOMMERCE_PRODUCT_CATEGORIES->url(), + [ + 'content' => $productName, + 'language' => $language, + 'max_quantity' => $maxQuantity, + 'voice_tone' => $voiceTone, + 'context' => $context, + ]); return $this->parseStatusUrl($response); } @@ -342,13 +459,22 @@ public function productCategories(string $productName, string $language = 'Engli * * @api */ - public function generateProductIntro(string $productData, string $language = 'English'): string + public function generateProductIntro( + string $productData, + ?string $language = null, + ?int $maxLength = null, + ?string $voiceTone = null + ): string { - $url = $this->apiBaseUrl . '/ecommerce/product_intro'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $productData, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::ECOMMERCE_PRODUCT_INTRO->url(), + [ + 'content' => $productData, + 'language' => $language, + 'max_length' => $maxLength, + 'voice_tone' => $voiceTone, + ]); return $this->parseStatusUrl($response); } @@ -362,13 +488,24 @@ public function generateProductIntro(string $productData, string $language = 'En * * @api */ - public function generateThankYouEmail(string $productName, string $language = 'English'): string + public function generateThankYouEmail( + string $productName, + ?string $language = null, + ?int $maxLength = null, + ?string $voiceTone = null, + ?string $context = null + ): string { - $url = $this->apiBaseUrl . '/ecommerce/thank_you_email'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $productName, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::ECOMMERCE_THANK_YOU_EMAIL->url(), + [ + 'content' => $productName, + 'language' => $language, + 'max_length' => $maxLength, + 'voice_tone' => $voiceTone, + 'context' => $context, + ]); return $this->parseStatusUrl($response); } @@ -384,10 +521,11 @@ public function generateThankYouEmail(string $productName, string $language = 'E */ public function detectPhones(string $text): string { - $url = $this->apiBaseUrl . '/content/detect_phones'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $text, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::CONTENT_DETECT_PHONES->url(), + ['content' => $text] + ); return $this->parseStatusUrl($response); } @@ -403,10 +541,11 @@ public function detectPhones(string $text): string */ public function detectEmails(string $text): string { - $url = $this->apiBaseUrl . '/content/detect_emails'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $text, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::CONTENT_DETECT_EMAILS->url(), + ['content' => $text] + ); return $this->parseStatusUrl($response); } @@ -421,47 +560,66 @@ public function detectEmails(string $text): string */ public function detectSpam(string $text): string { - $url = $this->apiBaseUrl . '/content/detect_spam'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $text, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::CONTENT_DETECT_SPAM->url(), + ['content' => $text] + ); return $this->parseStatusUrl($response); } /** - * Generates a list of unique keywords/tags based on the provided content. + * Generates a summarized version of the provided content. + * Perfect for generating marketing introductions of longer texts. * * @throws GuzzleException * * @api */ - public function generateKeywords(string $text, string $language = 'English'): string + public function summarizeText( + string $text, + ?string $language = null, + ?int $maxLength = null, + ?string $voiceTone = null + ): string { - $url = $this->apiBaseUrl . '/content/keywords'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $text, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::CONTENT_SUMMARIZE->url(), + [ + 'content' => $text, + 'language' => $language, + 'max_length' => $maxLength, + 'voice_tone' => $voiceTone, + ]); return $this->parseStatusUrl($response); } /** - * Generates a summarized version of the provided content. - * Perfect for generating marketing introductions of longer texts. + * Generates a list of unique keywords/tags based on the provided content. * * @throws GuzzleException * * @api */ - public function summarizeText(string $text, string $language = 'English'): string + public function generateKeywords( + string $text, + ?string $language = null, + ?int $maxQuantity = null, + ?string $voiceTone = null + ): string { - $url = $this->apiBaseUrl . '/content/summarize'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $text, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::CONTENT_KEYWORDS->url(), + [ + 'content' => $text, + 'language' => $language, + 'max_quantity' => $maxQuantity, + 'voice_tone' => $voiceTone, + ]); return $this->parseStatusUrl($response); } @@ -474,13 +632,79 @@ public function summarizeText(string $text, string $language = 'English'): strin * * @api */ - public function translate(string $text, string $language): string + public function translate( + string $text, + string $language, + ?string $voiceTone = null, + ?string $context = null + ): string + { + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::CONTENT_TRANSLATE->url(), + [ + 'content' => $text, + 'language' => $language, + 'voice_tone' => $voiceTone, + 'context' => $context, + ]); + + return $this->parseStatusUrl($response); + } + + /** + * Generates a paraphrased version of the provided text. + * Only the `content` parameter is required. You can define the output language, + * maximum character length, and tone of voice. Additional instructions + * on how to process the text can be provided in the context parameter. + * Please keep in mind that `max_length` serves as a strong suggestion + * for the Language Model, rather than a strict requirement, + * to maintain the general sense of the outcome. + * You can set your preferred writing style by providing an optional `voice_tone` parameter. + * It can be adjectives like `funny` or `joyous`, or even the name of a famous writer. + * This API method also provides an optional context parameter, + * which can be used to supply additional flexible instructions for content processing. + * + * @throws GuzzleException + * + * @api + */ + public function paraphrase( + string $text, + ?string $language = null, + ?int $maxLength = null, + ?string $voiceTone = null, + ?string $context = null + ): string + { + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::CONTENT_PARAPHRASE->url(), + [ + 'content' => $text, + 'language' => $language, + 'max_length' => $maxLength, + 'voice_tone' => $voiceTone, + 'context' => $context, + ]); + + return $this->parseStatusUrl($response); + } + + /** + * Proofreads (and checks grammar) of the provided text. + * + * @throws GuzzleException + * + * @api + */ + public function proofread(string $text): string { - $url = $this->apiBaseUrl . '/content/translate'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $text, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::CONTENT_PROOFREAD->url(), + ['content' => $text] + ); return $this->parseStatusUrl($response); } @@ -493,13 +717,20 @@ public function translate(string $text, string $language): string * * @api */ - public function generateSeoTags(string $text, string $language = 'English'): string + public function generateSeoTags( + string $text, + ?string $language = null, + ?string $voiceTone = null + ): string { - $url = $this->apiBaseUrl . '/seo/generate_tags'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $text, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::SEO_GENERATE_TAGS->url(), + [ + 'content' => $text, + 'language' => $language, + 'voice_tone' => $voiceTone, + ]); return $this->parseStatusUrl($response); } @@ -514,10 +745,11 @@ public function generateSeoTags(string $text, string $language = 'English'): str */ public function travelReviewSentiment(string $text): string { - $url = $this->apiBaseUrl . '/tth/review_sentiment'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $text, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::TTH_REVIEW_SENTIMENT->url(), + ['content' => $text] + ); return $this->parseStatusUrl($response); } @@ -533,19 +765,27 @@ public function travelReviewSentiment(string $text): string * @api */ public function toursAndActivitiesProductCategories( - string $productName, - string $city = '', - string $country = '', - string $language = 'English' + string $productName, + ?string $city = null, + ?string $country = null, + ?string $language = null, + ?int $maxQuantity = null, + ?string $voiceTone = null, + ?string $context = null ): string { - $url = $this->apiBaseUrl . '/tth/ta_product_categories'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $productName, - 'city' => $city, - 'country' => $country, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::TTH_TA_PRODUCT_CATEGORIES->url(), + [ + 'content' => $productName, + 'city' => $city, + 'country' => $country, + 'language' => $language, + 'max_quantity' => $maxQuantity, + 'voice_tone' => $voiceTone, + 'context' => $context, + ]); return $this->parseStatusUrl($response); } @@ -561,19 +801,27 @@ public function toursAndActivitiesProductCategories( * @api */ public function hospitalityProductCategories( - string $productName, - string $city = '', - string $country = '', - string $language = 'English' + string $productName, + ?string $city = null, + ?string $country = null, + ?string $language = null, + ?int $maxQuantity = null, + ?string $voiceTone = null, + ?string $context = null ): string { - $url = $this->apiBaseUrl . '/tth/hospitality_product_categories'; - $response = $this->makeRequest('POST', $url, [ - 'content' => $productName, - 'city' => $city, - 'country' => $country, - 'language' => $language, - ]); + $response = $this->makeRequest( + 'POST', + SharpApiJobTypeEnum::TTH_HOSPITALITY_PRODUCT_CATEGORIES->url(), + [ + 'content' => $productName, + 'city' => $city, + 'country' => $country, + 'language' => $language, + 'max_quantity' => $maxQuantity, + 'voice_tone' => $voiceTone, + 'context' => $context, + ]); return $this->parseStatusUrl($response); } From d15a218b73a02b155a856eea38c179c250ae5bcd Mon Sep 17 00:00:00 2001 From: Dawid Makowski Date: Fri, 3 May 2024 17:55:48 +0700 Subject: [PATCH 2/6] Update README.md --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b642a9d..44a479c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ ![SharpAPI GitHub cover](https://sharpapi.com/sharpapi-github-php-bg.jpg "SharpAPI Laravel Client") -# SharpAPI PHP Client - #AI Programming Interface +# SharpAPI PHP Client -### 🚀 AI-Powered Swiss Army Knife API +### 🚀 Automate with AI in just two lines of code. Save countless hours and enhance your app effortlessly. -## Save countless hours and supercharge your app with AI capabilities in just 2 lines of code. +## Leverage AI API to streamline workflows in E-Commerce, Marketing, Content Management, HR Tech, Travel, and more. [![Latest Version on Packagist](https://img.shields.io/packagist/v/sharpapi/sharpapi-php-client.svg?style=flat-square)](https://packagist.org/packages/sharpapi/sharpapi-php-client) [![Total Downloads](https://img.shields.io/packagist/dt/sharpapi/sharpapi-php-client.svg?style=flat-square)](https://packagist.org/packages/sharpapi/sharpapi-php-client) From e612a724cd133f7c59515453ef4fbf396c49e446 Mon Sep 17 00:00:00 2001 From: Dawid Makowski Date: Fri, 3 May 2024 18:02:40 +0700 Subject: [PATCH 3/6] Update README.md --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 44a479c..7b11210 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ ![SharpAPI GitHub cover](https://sharpapi.com/sharpapi-github-php-bg.jpg "SharpAPI Laravel Client") -# SharpAPI PHP Client +# SharpAPI PHP Client SDK -### 🚀 Automate with AI in just two lines of code. Save countless hours and enhance your app effortlessly. +## 🚀 Automate with AI in just two lines of code. Save countless hours and enhance your app effortlessly. -## Leverage AI API to streamline workflows in E-Commerce, Marketing, Content Management, HR Tech, Travel, and more. +### Leverage AI API to streamline workflows in E-Commerce, Marketing, Content Management, HR Tech, Travel, and more. [![Latest Version on Packagist](https://img.shields.io/packagist/v/sharpapi/sharpapi-php-client.svg?style=flat-square)](https://packagist.org/packages/sharpapi/sharpapi-php-client) [![Total Downloads](https://img.shields.io/packagist/dt/sharpapi/sharpapi-php-client.svg?style=flat-square)](https://packagist.org/packages/sharpapi/sharpapi-php-client) From e7901288ba506c2d5a9597aa43a69841f3596eb4 Mon Sep 17 00:00:00 2001 From: Dawid Makowski Date: Mon, 26 Aug 2024 19:16:05 +0200 Subject: [PATCH 4/6] release 1.2 --- CHANGELOG.md | 6 +++++- README.md | 12 +++++++----- composer.json | 3 ++- src/Dto/SharpApiJob.php | 8 ++++---- src/SharpApiService.php | 20 +++++++++++++++----- 5 files changed, 33 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 794fe50..f988dde 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog -## March 23, 2023 - v1.1.0 update +## August 26, 2024 - v1.2.0 update +- Generate Keywords/Tags & Summarize methods aquired optional `context` that allows to pass additional processing instructions for the provided `content` +- API useage optimized internall, switched to AI job dispatch/result endpoint pairing mode + +## March 23, 2024 - v1.1.0 update ### 1. new methods added diff --git a/README.md b/README.md index b642a9d..e87cfdf 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ # SharpAPI PHP Client - #AI Programming Interface -### 🚀 AI-Powered Swiss Army Knife API +### 🚀 Automate workflows with AI-powered API -## Save countless hours and supercharge your app with AI capabilities in just 2 lines of code. +## Leverage AI API to streamline workflows in E-Commerce, Marketing, Content Management, HR Tech, Travel, and more. [![Latest Version on Packagist](https://img.shields.io/packagist/v/sharpapi/sharpapi-php-client.svg?style=flat-square)](https://packagist.org/packages/sharpapi/sharpapi-php-client) [![Total Downloads](https://img.shields.io/packagist/dt/sharpapi/sharpapi-php-client.svg?style=flat-square)](https://packagist.org/packages/sharpapi/sharpapi-php-client) @@ -64,7 +64,7 @@ Please refer to the official: composer require sharpapi/sharpapi-php-client ``` -2. Register at [SharpApi.com](https://sharpapi.com/) and get the API key. +2. Register at [SharpAPI.com](https://sharpapi.com/) and get the API key. 3. **That's it!** @@ -483,7 +483,8 @@ $statusUrl = \SharpApiService::generateKeywords( $text, 'English', // optional language 5, // optional length - 'Freaky & Curious' // optional voice tone + 'Freaky & Curious', // optional voice tone + 'add emojis!' // optional extra context instructions for content processing ); ``` @@ -503,7 +504,8 @@ It can be adjectives like `funny` or `joyous`, or even the name of a famous writ $statusUrl = \SharpApiService::summarizeText( $text, 'English', // optional language - 'David Attenborough' // optional voice tone + 'David Attenborough', // optional voice tone + 'add emojis!' // optional extra context instructions for content processing ); ``` diff --git a/composer.json b/composer.json index a26ef36..212d659 100644 --- a/composer.json +++ b/composer.json @@ -36,7 +36,8 @@ "php": "^8.1", "guzzlehttp/guzzle": "^7.8", "kongulov/interact-with-enum": "^1.0", - "nesbot/carbon": "^3.0" + "nesbot/carbon": "^3.0", + "spatie/url": "^2.4" }, "autoload": { "psr-4": { diff --git a/src/Dto/SharpApiJob.php b/src/Dto/SharpApiJob.php index 315cf0d..b2f0b08 100644 --- a/src/Dto/SharpApiJob.php +++ b/src/Dto/SharpApiJob.php @@ -14,7 +14,7 @@ public function __construct( public string $id, public string $type, public string $status, - public ?string $result + public ?stdClass $result ) { } @@ -66,7 +66,7 @@ public function getStatus(): SharpApiJobStatusEnum */ public function getResultJson(): string|bool|null { - return $this->result ? json_encode(json_decode($this->result), JSON_PRETTY_PRINT) : null; + return $this->result ? json_encode($this->result, JSON_PRETTY_PRINT) : null; } /** @@ -76,7 +76,7 @@ public function getResultJson(): string|bool|null */ public function getResultArray(): ?array { - return $this->result ? json_decode($this->result, true) : null; + return (array) $this->result; } /** @@ -86,6 +86,6 @@ public function getResultArray(): ?array */ public function getResultObject(): ?stdClass { - return $this->result ? json_decode($this->result) : null; + return $this->result; } } diff --git a/src/SharpApiService.php b/src/SharpApiService.php index fde115e..21b590d 100644 --- a/src/SharpApiService.php +++ b/src/SharpApiService.php @@ -15,6 +15,7 @@ use SharpAPI\SharpApiService\Dto\SharpApiSubscriptionInfo; use SharpAPI\SharpApiService\Enums\SharpApiJobStatusEnum; use SharpAPI\SharpApiService\Enums\SharpApiJobTypeEnum; +use Spatie\Url\Url; /** * Main Service to dispatch AI jobs to SharpAPI.com @@ -49,7 +50,7 @@ public function __construct(string $apiKey, ?string $apiBaseUrl = null, ?string throw new InvalidArgumentException('API key is required.'); } $this->setApiBaseUrl($apiBaseUrl ?? 'https://sharpapi.com/api/v1'); - $this->setUserAgent($userAgent ?? 'SharpAPIPHPAgent/1.1.0'); + $this->setUserAgent($userAgent ?? 'SharpAPIPHPAgent/1.2.0'); } /** @@ -220,12 +221,17 @@ public function fetchResults(string $statusUrl): SharpApiJob sleep($retryAfter); } while (true); $data = json_decode($response->getBody()->__toString(), true)['data']; - + $url = Url::fromString($statusUrl); + if (count($url->getSegments()) == 5) { // shared job result URL + $result = (object) json_decode($data['attributes']['result']); + } else { // 7 segments, 1-to-1 job to result url + $result = (object) $data['attributes']['result']; + } return new SharpApiJob( id: $data['id'], type: $data['attributes']['type'], status: $data['attributes']['status'], - result: $data['attributes']['result'] ?? null + result: $result ?? null ); } @@ -581,7 +587,8 @@ public function summarizeText( string $text, ?string $language = null, ?int $maxLength = null, - ?string $voiceTone = null + ?string $voiceTone = null, + ?string $context = null ): string { $response = $this->makeRequest( @@ -592,6 +599,7 @@ public function summarizeText( 'language' => $language, 'max_length' => $maxLength, 'voice_tone' => $voiceTone, + 'context' => $context, ]); return $this->parseStatusUrl($response); @@ -608,7 +616,8 @@ public function generateKeywords( string $text, ?string $language = null, ?int $maxQuantity = null, - ?string $voiceTone = null + ?string $voiceTone = null, + ?string $context = null ): string { $response = $this->makeRequest( @@ -619,6 +628,7 @@ public function generateKeywords( 'language' => $language, 'max_quantity' => $maxQuantity, 'voice_tone' => $voiceTone, + 'context' => $context, ]); return $this->parseStatusUrl($response); From 267ef4fd22371932b420734e6deab7330553be79 Mon Sep 17 00:00:00 2001 From: Dawid Makowski Date: Mon, 26 Aug 2024 19:23:14 +0200 Subject: [PATCH 5/6] readme update --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d7093c6..7cb7842 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ # SharpAPI PHP Client SDK -### 🚀 AI-Powered Swiss Army Knife API +### 🚀 Automate workflows with AI-powered API -## Save countless hours and supercharge your app with AI capabilities in just 2 lines of code. +## Leverage AI API to streamline workflows in E-Commerce, Marketing, Content Management, HR Tech, Travel, and more. [![Latest Version on Packagist](https://img.shields.io/packagist/v/sharpapi/sharpapi-php-client.svg?style=flat-square)](https://packagist.org/packages/sharpapi/sharpapi-php-client) [![Total Downloads](https://img.shields.io/packagist/dt/sharpapi/sharpapi-php-client.svg?style=flat-square)](https://packagist.org/packages/sharpapi/sharpapi-php-client) From e6efb02b7d62d91c20ceee8a2006da5db21ab237 Mon Sep 17 00:00:00 2001 From: Dawid Makowski Date: Tue, 27 Aug 2024 13:34:11 +0200 Subject: [PATCH 6/6] Update CHANGELOG.md --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f988dde..9bb0ac5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## August 26, 2024 - v1.2.0 update - Generate Keywords/Tags & Summarize methods aquired optional `context` that allows to pass additional processing instructions for the provided `content` -- API useage optimized internall, switched to AI job dispatch/result endpoint pairing mode +- API usege optimized internally, switched to AI job dispatch/result endpoint pairing mode ## March 23, 2024 - v1.1.0 update @@ -119,4 +119,4 @@ SHARP_API_USER_AGENT="SharpAPIPHPAgent/1.1.0" More info at https://sharpapi.com/affiliate_program ## December 10, 2023 - v1.0.2 -- v1.0.2 initial release \ No newline at end of file +- v1.0.2 initial release