From e7cf4f1e09702c29d7a4c955d3161db8f76b223a Mon Sep 17 00:00:00 2001 From: Jezza Hehn Date: Sat, 18 Apr 2026 02:47:33 +0000 Subject: [PATCH] docs: fix parameter mismatches and inaccurate documentation - Fix update_post() wrapper documentation (post_id -> post_text/post_path/post_key) - Fix create_comment() wrapper documentation (added post_slug, post_key parameters) - Add missing wrapper docs for follow(), trust(), votecast(), react() - Fix reaction job parameters (parent_id -> parent_sk, corrected payload structure) - Fix trust job parameters (updated to match actual payload structure) - Fix vote job parameters (voteType -> vote, added parent structure) - Clearly mark Block and Mute jobs as NOT IMPLEMENTED - Fix GitLab URLs to Forgejo (git.jezzahehn.com) - Remove LLM-style language (comprehensive -> full/thorough) - Fix trust listbyusersinit parameter (username -> user_id) --- README.md | 2 +- development.md | 2 +- docs/API_REFERENCE.md | 114 ++++++++-------- docs/INDEX.md | 6 +- docs/TROUBLESHOOTING.md | 4 +- docs/WRAPPERS.md | 287 +++++++++++++++++++++++++++++++++++----- 6 files changed, 320 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index fcce906..f479403 100644 --- a/README.md +++ b/README.md @@ -620,7 +620,7 @@ python -m pytest tests/ For issues, questions, or contributions: - [TrustCafé Website](https://trustcafe.io) -- [GitLab Repository](https://gitlab.com/trustcafe/trustcafe-api-wrapper) +- [Forgejo Repository](https://git.jezzahehn.com/KrustyPlanet/trustcafe-api-wrapper) - Contact the WikiTribune team ## Version History diff --git a/development.md b/development.md index 9671e0d..a22e9ae 100644 --- a/development.md +++ b/development.md @@ -614,7 +614,7 @@ if __name__ == '__main__': - Follow PEP 8 - Use type hints -- Write comprehensive docstrings +- Write thorough docstrings - Add error handling - Include examples in docstrings diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index fdce04c..15c3bc1 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -365,25 +365,32 @@ Cast votes on posts/content. ### vote.votecast() -Casts a vote on a post. +Casts a vote on a post or comment. ```python vote = API.run_job('vote.votecast', payload) ``` **Parameters:** -- `pk` (str): Object partition key -- `sk` (str): Object sort key -- `voteType` (str): Vote type - "up" or "down" +- `parent` (dict): Object containing vote target info + - `pk` (str): Object partition key + - `sk` (str): Object sort key + - `slug` (str): Object slug + - `entity` (str): Entity type (e.g., "post", "comment") +- `vote` (str): Vote type - "up" or "down" **Returns:** dict - Vote status **Example:** ```python voted = API.run_job('vote.votecast', { - "pk": "post-id", - "sk": "post-id", - "voteType": "up" + "parent": { + "pk": "post#abc123", + "sk": "post#abc123", + "slug": "my-post-slug", + "entity": "post" + }, + "vote": "up" }) ``` @@ -402,20 +409,21 @@ reaction = API.run_job('reaction.reacttosomething', payload) ``` **Parameters:** -- `objectPK` (str): Object partition key -- `objectSK` (str): Object sort key -- `objectType` (str): Type of object ("post", "comment", etc.) -- `reactionType` (str): Reaction type (depends on API) +- `parent` (dict): Object containing `pk` and `sk` keys + - `pk` (str): Object partition key + - `sk` (str): Object sort key +- `reaction` (str): Reaction type (e.g., "like", "heart", "fire") **Returns:** dict - Reaction status **Example:** ```python reacted = API.run_job('reaction.reacttosomething', { - "objectPK": "post-id", - "objectSK": "post-id", - "objectType": "post", - "reactionType": "like" + "parent": { + "pk": "post-id", + "sk": "post-id" + }, + "reaction": "like" }) ``` @@ -423,16 +431,21 @@ reacted = API.run_job('reaction.reacttosomething', { ### reaction.getbyparent() -Get reactions by parent object. +Get a specific reaction by parent sort key. ```python -reactions = API.run_job('reaction.getbyparent', parent_id) +reactions = API.run_job('reaction.getbyparent', parent_sk) ``` **Parameters:** -- `objectId` (str): Parent object ID +- `parent_sk` (str): Parent sort key (not full ID) -**Returns:** dict - List of reactions +**Returns:** dict - Reaction data + +**Example:** +```python +reaction = API.run_job('reaction.getbyparent', "post#my-post-slug") +``` --- @@ -441,15 +454,19 @@ reactions = API.run_job('reaction.getbyparent', parent_id) List all reactions for a parent object. ```python -reactions = API.run_job('reaction.listbyparent', parent_id) +reactions = API.run_job('reaction.listbyparent', parent_sk) ``` **Parameters:** -- `parentPK` (str): Parent partition key -- `parentSK` (str): Parent sort key +- `parent_sk` (str): Parent sort key (not full ID) **Returns:** dict - List of reactions +**Example:** +```python +reactions = API.run_job('reaction.listbyparent', "post#my-post-slug") +``` + --- ## Notification Jobs @@ -509,19 +526,21 @@ trust = API.run_job('trust.createorupdate', payload) ``` **Parameters:** -- `pk` (str): Trust identifier (partition key) -- `sk` (str): Trust identifier (sort key) -- `trustType` (str): Trust type ("positive", "negative", etc.) -- Other optional fields +- `parent` (dict): Object containing `pk` and `sk` for the userprofile +- `parentSlug` (str): Slug of the userprofile +- `trustLevel` (str): Trust level (e.g., "trusted", "neutral", "distrusted") **Returns:** dict - Trust relationship status **Example:** ```python trust = API.run_job('trust.createorupdate', { - "pk": "trust-id-123", - "sk": "trust-id-123", - "trustType": "positive" + "parent": { + "pk": "userprofile#philosopher-jon", + "sk": "userprofile#philosopher-jon" + }, + "parentSlug": "philosopher-jon", + "trustLevel": "trusted" }) ``` @@ -532,17 +551,18 @@ trust = API.run_job('trust.createorupdate', { Lists trust relationships initialized by a user. ```python -trusts = API.run_job('trust.listbyusersinit', username) +trusts = API.run_job('trust.listbyusersinit', user_id) ``` **Parameters:** -- `username` (str): The user whose trust relationships to list +- `user_id` (str): The user ID (not username) whose trust relationships to list +- `lastEvaluatedKey` (dict, optional): Pagination key **Returns:** dict - List of trust relationships **Example:** ```python -my_trusts = API.run_job('trust.listbyusersinit', "your-username") +my_trusts = API.run_job('trust.listbyusersinit', "user-id-123") ``` --- @@ -552,11 +572,11 @@ my_trusts = API.run_job('trust.listbyusersinit', "your-username") Lists trust relationships where a user was the target. ```python -trusts = API.run_job('trust.listbyuserhas', username) +trusts = API.run_job('trust.listbyuserhas', user_id) ``` **Parameters:** -- `username` (str): The user who was targeted +- `user_id` (str): The user ID (not username) who was targeted **Returns:** dict - List of trust relationships @@ -653,35 +673,21 @@ print(f"Following feed items: {len(following_feed.get('Items', []))}") ## Block Jobs -Block users or content. +### ⚠️ NOT IMPLEMENTED -### block.[notimplemented] +Block functionality is not yet implemented in this wrapper. The TrustCafé API may support blocking, but no job or wrapper functions exist yet. -Block functionality is defined in the backend but not yet implemented in the wrapper. - -**Status:** TODO - -**Implementation needed:** -- Job function creation -- Payload structure definition -- Error handling +**Status:** TODO - See development.md for details --- ## Mute Jobs -Mute users or content. +### ⚠️ NOT IMPLEMENTED -### mute.[notimplemented] +Mute functionality is not yet implemented in this wrapper. The TrustCafé API may support muting, but no job or wrapper functions exist yet. -Mute functionality is pending implementation. - -**Status:** TODO - -**Implementation needed:** -- Job function creation -- Payload structure definition -- Error handling +**Status:** TODO - See development.md for details --- diff --git a/docs/INDEX.md b/docs/INDEX.md index 2bc5f3e..9c35c4a 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -118,7 +118,7 @@ If you can't find the answer you're looking for: 1. **Check the FAQs section** - Common questions and answers 2. **Review the Troubleshooting guide** - For specific error handling 3. **Contact WikiTribune team** - Via company channels -4. **File an issue on GitLab** - [Repository Issues](https://gitlab.com/trustcafe/trustcafe-api-wrapper/-/issues) +4. **File an issue on Forgejo** - [Repository Issues](https://git.jezzahehn.com/KrustyPlanet/trustcafe-api-wrapper/issues) --- @@ -128,7 +128,7 @@ Document version updates should be listed here. ### v0.2.0 (Current) - Complete rewrite and enhancement of all documentation -- Added comprehensive API reference +- Added full API reference - Added wrappers guide - Added custom requests guide - Added detailed troubleshooting section @@ -159,4 +159,4 @@ When contributing documentation remember: --- -**Last Updated:** April 17, 2026 +**Last Updated:** April 18, 2026 diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 523127f..d6193af 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -729,8 +729,8 @@ requests_log.propagate = True If you've tried all of the above and still have issues: -1. **Check the Code**: Review the latest version on GitLab - - [GitLab Repository](https://gitlab.com/trustcafe/trustcafe-api-wrapper) +1. **Check the Code**: Review the latest version on Forgejo + - [Forgejo Repository](https://git.jezzahehn.com/KrustyPlanet/trustcafe-api-wrapper) 2. **Check TrustCafé Status**: Verify services are up - [Production](https://trustcafe.io) diff --git a/docs/WRAPPERS.md b/docs/WRAPPERS.md index 04c2a5c..d6953fd 100644 --- a/docs/WRAPPERS.md +++ b/docs/WRAPPERS.md @@ -157,8 +157,9 @@ Updates an existing post. from trustcafeapiwrapper.wrappers.post.update_post import update_post API.wrapped(update_post( - post_id="post-uuid", - new_post_text="New post content" + post_text="New post content", + post_path="my-post-slug", # OR use post_key + parent_path="/" )) ``` @@ -166,15 +167,19 @@ API.wrapped(update_post( | Parameter | Type | Default | Description | |-----------|------|---------|-------------| -| `post_id` | str | **Required** | The post to update (pk/sk) | -| `new_post_text` | str | **Required** | The new post content | -| Optional fields per the API (e.g., blurLabel, cardUrl, etc.) +| `post_text` | str | **Required** | The new post content | +| `post_path` | str | `None` | The slug of the post to update | +| `parent_path` | str | `'/'` | Parent path for the post | +| `post_key` | dict | `None` | Direct pk/sk dict if you have it | +| `blur_label` | str | `None` | Optional blur label for content | +| `card_url` | str | `None` | Optional URL for link preview card | +| `collaborative` | bool | `False` | Enable collaborative editing | -**Returns:** dict - Updated post data +**Returns:** dict - Job specification for update operation -**Important:** The post_id parameter should be set to the post's pk/sk. The wrapper internally maps the update parameters to the API's update payload structure. +**Important:** You must provide either `post_key` OR both `post_path` and `parent_path`. -**Example - Update Text:** +**Example - Update with Path:** ```python from trustcafeapiwrapper.wrappers.post.update_post import update_post @@ -182,31 +187,33 @@ from trustcafeapiwrapper.wrappers.post.update_post import update_post API.handle_token() API.wrapped(update_post( - post_id="current-pk-same-as-sk", - new_post_text="Updated content here" + post_text="Updated content here", + post_path="my-post-slug", + parent_path="/music" )) ``` -**Example - Update with Optional Fields:** +**Example - Update with Key:** ```python API.wrapped(update_post( - post_id="current-pk-same-as-sk", - new_post_text="Updated with new card", - card_url="https://example.com/resource" + post_text="Updated with key", + post_key={"pk": "post#123", "sk": "post#123"} )) ``` -**Example - Update Blur Label:** +**Example - Update with Blur:** ```python API.wrapped(update_post( - post_id="current-pk-same-as-sk", - blur_label="sensitive" + post_text="Sensitive content", + post_path="my-post", + parent_path="/", + blur_label="nsfw" )) ``` -See update_post.py for mapping of updated fields to the server payload. +See update_post.py for full implementation details. ## Comment Wrappers @@ -217,9 +224,17 @@ Creates a new comment on a post. ```python from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment +# Option 1: Using post_key API.wrapped(create_comment( comment_text="This is a comment", - parent_path="/" + post_key={"pk": "post#123", "sk": "post#123"} +)) + +# Option 2: Using parent_path + post_slug +API.wrapped(create_comment( + comment_text="This is a comment", + parent_path="/userprofile/my-username", + post_slug="my-post-slug" )) ``` @@ -228,11 +243,17 @@ API.wrapped(create_comment( | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `comment_text` | str | **Required** | The comment content | -| `parent_path` | str | **Required** | Path to the parent post where comment will be created | +| `post_slug` | str | `None` | Slug of the post to comment on (required if not using post_key) | +| `parent_path` | str | `None` | Path in format `'userprofile/slug'` or `'subwiki/slug'` | +| `post_key` | dict | `None` | Direct pk/sk dict for the post | +| `blur_label` | str | `None` | Optional blur label for content | +| `version` | int | `3` | Comment structure version | -**Returns:** dict - Job execution result, contains success information +**Returns:** dict - Job specification for create operation -**Example - Basic Comment:** +**Important:** You must provide either `post_key` OR both `parent_path` AND `post_slug`. + +**Example - Using post_key:** ```python from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment @@ -240,30 +261,29 @@ from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment API.handle_token() API.wrapped(create_comment( - "Great post! I really enjoyed reading it.", - parent_path="/" + comment_text="Great post! I really enjoyed reading it.", + post_key={"pk": "post#abc123", "sk": "post#abc123"} )) ``` -**Example - Comment on a Post:** +**Example - Using parent_path and post_slug:** ```python -# First get the post to find its path -post = API.run_job('post.get', "target-post-id") - -# Then create a comment API.wrapped(create_comment( - "I agree with your point about this.", - parent_path="/music" # Path to the post + comment_text="I agree with your point.", + parent_path="/userprofile/philosopher-jon", + post_slug="my-thoughts-on-truth" )) ``` -**Example - Collaborative Comment:** +**Example - With blur label:** ```python API.wrapped(create_comment( - "Let's work on this together!", - parent_path="/current-post" + comment_text="Spoiler content warning.", + parent_path="/subwiki/movies", + post_slug="movie-review", + blur_label="spoiler" )) ``` @@ -489,6 +509,205 @@ result = create_in_branch(API, "music", "New music discussion") result = create_in_branch(API, "science", "Research paper abstract", create_card=True) ``` +## Follow Wrappers + +### follow() + +Follow or unfollow a user or subwiki. + +```python +from trustcafeapiwrapper.wrappers.follow.follow import follow + +API.wrapped(follow( + entity="userprofile", + is_following=True, + parent_slug="philosopher-jon" +)) +``` + +**Parameters:** + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `entity` | str | **Required** | Type of entity: `'userprofile'` or `'subwiki'` | +| `is_following` | bool | **Required** | `True` to follow, `False` to unfollow | +| `parent_slug` | str | **Required** | Slug of the user or subwiki to follow | + +**Returns:** dict - Job specification for follow operation + +**Example - Follow a user:** + +```python +from trustcafeapiwrapper.wrappers.follow.follow import follow + +API.handle_token() + +API.wrapped(follow( + entity="userprofile", + is_following=True, + parent_slug="philosopher-jon" +)) +``` + +**Example - Unfollow a subwiki:** + +```python +API.wrapped(follow( + entity="subwiki", + is_following=False, + parent_slug="music" +)) +``` + +--- + +## Trust Wrappers + +### trust() + +Set trust level for a user. + +```python +from trustcafeapiwrapper.wrappers.trust.trust import trust + +API.wrapped(trust( + trustLevel="trusted", + userprofile_path="/userprofile/philosopher-jon" +)) +``` + +**Parameters:** + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `trustLevel` | str | **Required** | Trust level to set (e.g., `'trusted'`, `'neutral'`, `'distrusted'`) | +| `userprofile_path` | str | **Required** | Path to the user profile | + +**Returns:** dict - Job specification for trust operation + +**Example:** + +```python +from trustcafeapiwrapper.wrappers.trust.trust import trust + +API.handle_token() + +API.wrapped(trust( + trustLevel="trusted", + userprofile_path="/userprofile/some-user" +)) +``` + +--- + +## Vote Wrappers + +### votecast() + +Cast a vote on a post or comment. + +```python +from trustcafeapiwrapper.wrappers.vote.votecast import votecast + +# Option 1: Using item_key +API.wrapped(votecast( + vote="up", + item_key={"pk": "post#123", "sk": "post#123"} +)) + +# Option 2: Using parent_path and item_path +API.wrapped(votecast( + vote="down", + parent_path="/userprofile/my-username", + item_path="my-post-slug" +)) +``` + +**Parameters:** + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `vote` | str | **Required** | Vote type: `'up'` or `'down'` | +| `parent_path` | str | `None` | Parent path (required if not using item_key) | +| `item_path` | str | `None` | Item slug (required if not using item_key) | +| `item_key` | dict | `None` | Direct pk/sk dict for the item | + +**Returns:** dict - Job specification for vote operation + +**Example - Upvote with key:** + +```python +from trustcafeapiwrapper.wrappers.vote.votecast import votecast + +API.handle_token() + +API.wrapped(votecast( + vote="up", + item_key={"pk": "post#abc", "sk": "post#abc"} +)) +``` + +**Example - Downvote with paths:** + +```python +API.wrapped(votecast( + vote="down", + parent_path="/subwiki/politics", + item_path="controversial-post" +)) +``` + +--- + +## Reaction Wrappers + +### react() + +React to a post or comment. + +```python +from trustcafeapiwrapper.wrappers.reaction.react import react + +# Option 1: Using item_key +API.wrapped(react( + reaction_type="like", + item_key={"pk": "post#123", "sk": "post#123"} +)) + +# Option 2: Using parent_path and item_path +API.wrapped(react( + reaction_type="heart", + parent_path="/userprofile/my-username", + item_path="my-post-slug" +)) +``` + +**Parameters:** + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `reaction_type` | str | **Required** | Type of reaction (e.g., `'like'`, `'heart'`, `'fire'`) | +| `parent_path` | str | `None` | Parent path (required if not using item_key) | +| `item_path` | str | `None` | Item slug (required if not using item_key) | +| `item_key` | dict | `None` | Direct pk/sk dict for the item | + +**Returns:** dict - Job specification for reaction operation + +**Important:** You must provide either `item_key` OR both `parent_path` AND `item_path`. + +**Example:** + +```python +from trustcafeapiwrapper.wrappers.reaction.react import react + +API.handle_token() + +API.wrapped(react( + reaction_type="fire", + item_key={"pk": "post#123", "sk": "post#123"} +)) +``` + --- ## Summary