Add docs for post update events (#127)

* Add docs for post update events

* Add note for post updates

ReadMe.md

@@ -199,7 +199,7 @@
 | response_type   | code       |  مقدار بازگشتی بعد از ریدایرکت کاربر از صفحهٔ احراز باز دیوار به صفحهٔ شما که در پارامتر `redirect_uri` مشخص می‌کنید |
 | client_id       | <app-slug> |  نام یکتای برنامهٔ شما که در قسمت مدیریت برنامه‌ٔ پنل کنار دیوار می‌توانید ببینید |
 | redirect_uri    | <url>      |  آدرسی از برنامهٔ شما که کاربر بعد از صدور (یا رد) اجازه‌های درخواستی به آن هدایت شود. (این آدرس باید URL encoded باشد، در فهرست آدرس‌های مجاز برنامهٔ شما در پنل کنار ثبت شده‌باشد و هیچ پارامتری در آن نباشد.) |
-| scope           | <scope>    |  جازه‌های مورد نیاز برای دریافت از کاربر که با اسپیس (‍‍`" "`) از هم جدا شدند. |
+| scope           | <scope>    |  جازه‌های مورد نیاز برای دریافت از کاربر که با اسپیس (`" "`) از هم جدا شدند. |
 | state           | <state>    |  ک مقدار دلخواه که در بازگشت کاربر به اپلیکیشن شما مجدد در پارامترهای URL قرار می‌گیرد. |
 ### گام دوم (بازگشت به برنامهٔ شما)
 کاربر به آدرس `redirect_uri` که در گام اول مشخص کردید با پارامترهای زیر ریدایرکت می‌شود.
@@ -244,7 +244,6 @@ POST https://api.divar.ir/oauth2/token
   - [ویجت‌ها » فیگما][ویجت‌ها » فیگما]
 - [افزونه‌های چت][راهنما » افزونه‌های چت]
   - [افزونه‌های چت » ارسال پیام][راهنما » افزونه‌های چت » ارسال پیام]
-  - [افزونه‌های چت » محیط تست][راهنما » افزونه‌های چت »‌ تست]
 - [احراز باز][راهنما » احراز باز]
   - [احراز باز » ابزارها][احراز باز » ابزارها]
 - [افزونه‌های کاربر][راهنما » افزونه‌های کاربر]

events/ReadMe.md

@@ -15,14 +15,13 @@ Backward incompatible
 ## درخواست گوش دادن به یک رویداد
 
 برای ارسال این درخواست برنامه‌ی شما باید دسترسی `EVENTS_REGISTER_SUBSCRIPTION` را داشته باشد.
-دقت کنید که این یک دسترسی OAuth نیست
+دقت کنید که این یک دسترسی OAuth نیست، بلکه این دسترسی بر روی کلید API شما تعریف می‌شود.
 
-همچنین برای گوش دادن به هر نوع رویداد، دسترسی Oauth متناظر با آن نیز باید در توکن همراه آگهی وجود
+همچنین برای گوش دادن به هر نوع رویداد، دسترسی Oauth متناظر با آن نیز باید در توکن همراه درخواست گوش دادن به آن وجود
 داشته باشد.
 
 در صورت موفق بودن این درخواست، شما تا زمان معتبر بودن توکن تان از رویداد‌های درخواستی مطلع خواهید شد.
-بدیهی است که با توجه به تغییر توکن در زمان رفرش کردن آن، در صورت نیاز باید درخواست جدیدی
-برای مطلع شدن از رویدادهای بفرستید.
+در صورتی که نیاز به refresh کردن توکن دارید، باید پس از دریافت توکن جدید، درخواستی برای ساختن مجدد subscription تان بزنید.
 
 ## انواع رویداد‌ها
 
@@ -32,13 +31,14 @@ Backward incompatible
 |  NEW_MESSAGE_ON_POST   |    `CHAT_SUPPLIER_ALL_CONVERSATIONS_READ`     | مطلع شدن از پیام‌های جدید بر روی تمام چت‌های تمام آگهی‌های یک فرد. **فقط برای چت های مربوط به آگهی گذار** |
 |  NEW_CHATBOT_MESSAGE   |                       -                       |                                                                   مطلع شدن از پیام جدید کاربران به چت بات |
 | USER_ACCESS_REVOCATION | `NOTIFICATION_ACCESS_REVOCATION` و `USER_ID`  |                                                          مطلع شدن از حذف شدن دسترسی‌های برنامه توسط کاربر |
+|      POST_UPDATE       |               `USER_POSTS_GET`                |                                                       مطلع شدن از تغییرات آگهی‌ منتشر شده و آگهی در جریان |
 
 ## درخواست
 
-|       پارامتر       |  نوع   |                                                                         توضیحات |
-|:-------------------:|:------:|--------------------------------------------------------------------------------:|
-|    `event_type`     | string |                            یک نوع رویداد معتبر. برای مثال `NEW_MESSAGE_ON_POST` |
-| `event_resource_id` | string | شناسهٔ چیزی که می خواهید از رویداد آن باخبر شوید و نوعش رو در بالا گفتید. اگر ارسال نشود همهٔ موارد در نظر گرفته می شود. مثلاً می توانید با ارسال توکن آگهی پیام های جدید یک آگهی را دریافت کنید و بدون ارسال آن پیام های جدید همهٔ آگهی را دریافت می کنید.|
+|       پارامتر       |  نوع   |                                                                                                                                                                                                                                                     توضیحات |
+|:-------------------:|:------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
+|    `event_type`     | string |                                                                                                                                                                                     یک نوع [رویداد معتبر](#انواع-رویدادها). برای مثال `NEW_MESSAGE_ON_POST` |
+| `event_resource_id` | string | شناسهٔ چیزی که می خواهید از رویداد آن باخبر شوید و نوعش رو در بالا گفتید. اگر ارسال نشود همهٔ موارد در نظر گرفته می شود. مثلاً می توانید با ارسال توکن آگهی پیام های جدید یک آگهی را دریافت کنید و بدون ارسال آن پیام های جدید همهٔ آگهی را دریافت می کنید. |
 
 ```http request
 POST https://api.divar.ir/v1/open-platform/events/subscriptions
@@ -92,13 +92,14 @@ Content-Type: application/json
 
 ## درخواست رویداد جدید (ارسالی از سمت دیوار)
 
-|         پارامتر          |                                   نوع                                    |                                                                            توضیحات |
-|:------------------------:|:------------------------------------------------------------------------:|-----------------------------------------------------------------------------------:|
-|          `type`          |                          [EventType](#رویدادها)                          |                                                نوع رویداد، برای مثال `NEW_MESSAGE` |
-|      `new_message`       |          Optional[[ChatMessage](/events/chat.md/#chat-message)]          |                               پیام جدید. در صورتی که نوع رویداد `NEW_MESSAGE` باشد |
-|  `new_chatbot_message`   |          Optional[[ChatMessage](/events/chat.md/#chat-message)]          |                       پیام جدید. در صورتی که نوع رویداد `NEW_CHATBOT_MESSAGE` باشد |
-| `user_access_revocation` | Optional[[UserAccessRevocation](/events/auth.md/#user-access-revocation) | حذف دسترسی برنامه توسط کاربر. در صورتی که نوع رویداد `USER_ACCESS_REVOCATION` باشد |
-|        `metadata`        |                             Optional[Object]                             |                                                  دیتای دلخواه از سمت برنامه‌ی شما. |
+|         پارامتر          |                                    نوع                                    |                                                                            توضیحات |
+|:------------------------:|:-------------------------------------------------------------------------:|-----------------------------------------------------------------------------------:|
+|          `type`          |                          [EventType](#رویدادها)                           |                                                نوع رویداد، برای مثال `NEW_MESSAGE` |
+|      `new_message`       |          Optional[[ChatMessage](/events/chat.md/#chat-message)]           |                               پیام جدید. در صورتی که نوع رویداد `NEW_MESSAGE` باشد |
+|  `new_chatbot_message`   |          Optional[[ChatMessage](/events/chat.md/#chat-message)]           |                       پیام جدید. در صورتی که نوع رویداد `NEW_CHATBOT_MESSAGE` باشد |
+| `user_access_revocation` | Optional[[UserAccessRevocation](/events/auth.md/#user-access-revocation)] | حذف دسترسی برنامه توسط کاربر. در صورتی که نوع رویداد `USER_ACCESS_REVOCATION` باشد |
+|      `post_update`       |           Optional[[PostUpdate](/events/post.md/#post-update)]            |        تغییر آگهی منتشر شده یا در جریان. در صورتی که نوع رویداد `POST_UPDATE` باشد |
+|        `metadata`        |                             Optional[Object]                              |                                                  دیتای دلخواه از سمت برنامه‌ی شما. |
 
 ### رویدادها
 
@@ -107,3 +108,4 @@ Content-Type: application/json
 |      `NEW_MESSAGE`       |              پیام جدید در چت |
 |  `NEW_CHATBOT_MESSAGE`   |          پیام جدید در چت بات |
 | `USER_ACCESS_REVOCATION` | حذف دسترسی برنامه توسط کاربر |
+|      `POST_UPDATE`       |                   تغییر آگهی |

events/post.md

@@ -0,0 +1,47 @@
+# Post Update
+
+هر تغییری در پست‌های منتشر شده یا در جریان رخ بدهد با این event به شما اطلاع داده می‌شود.
+
+توجه کنید که نرخ آپدیت‌های رو پست زیاد است و با توجه به این که تمام فیلد‌های پست به شما داده نمی‌شود،
+ممکن است از دید شما، آپدیت‌هایی تکراری به شما داده شود.
+
+
+برای اطلاعات در مورد پست می‌توانید به
+[این صفحه](/misc/post.md)
+مراجعه کنید.
+
+| پارامتر |      نوع      | توضیحات        |
+|:-------:|:-------------:|----------------|
+| `type`  | Enum[string]  | نوع تغییر آگهی |
+| `post`  | [Post](#post) | اطلاعات پست    |
+
+
+## Type
+توجه کنید ممکن است در آینده به این مقادیر اضافه شود.
+- `PUBLISH`
+- `RETIRE`
+- `ARCHIVE`
+- `ONGOING`
+
+در صورتی که رویداد از نوع
+`RETIRE`
+یا
+`ARCHIVE`
+باشد، تنها توکن آگهی به شما داده می‌شود.
+
+## Post
+
+اطلاعات پست مشابه اطلاعات موجود در جواب
+[/finder/post/{post-token}](/finder/get_post.md#پاسخ)
+است.
+
+|       پارامتر        |   نوع    | توضیحات                             |
+|:--------------------:|:--------:|-------------------------------------|
+|       `token`        |  string  | توکن آگهی                           |
+|      `category`      |  string  | دسته‌بندی آگهی                      |
+|        `city`        |  string  | شهر                                 |
+|      `district`      |  string  | محله                                |
+|    `chat_enabled`    | boolean  | آیا چت دیوار برای این آگهی فعال است |
+| `first_published_at` | datetime | زمان اولین انتشار این آگهی          |
+|        `data`        |  Object  | سایر فیلد‌های آگهی                  |
+

misc/post.md

@@ -0,0 +1,10 @@
+# آگهی‌های دیوار
+
+
+## وضعیت‌های آگهی 
+
+<img src="/img/post-states.svg" alt="یک نمودار جریان که چرخه حیات فرآیند ارسال پست را نشان می‌دهد. حالت‌ها شامل Submit، Under Review، Published، Retired، Archived، Needs Edit و Waiting for Payment هستند. پیکان‌ها انتقال بین حالت‌ها را نشان می‌دهند، مانند Submit که به Under Review می‌رود، Published، رد شدن که نیاز به Needs Edit دارد، و Retired که منجر به Archived می‌شود.">
+
+## اگهی منتشر شده و در جریان 
+تمامی‌ آگهی‌هایی که در لیستینگ دیوار مشاهده می‌شوند آگهی منتشر شده هستند.
+آگهی‌هایی که کاربران در پنل مدیریت آگهی در دیوار من مشاهده می‌کنند آگهی‌های در جریان هستند. آگهی‌های در جریان، می‌توانند منتشر شده باشند.