doc: audit pass — fix env= bug, params, pagination, missing wrappers, broken examples
- env= -> environment= across all docs (Pydantic silently ignores env=) - Remove __version__ check (doesn't exist in module) - Fix APIClient(debug=True) missing required client_id/secret - Fix post.listremoved usage (takes no postId, just lists removed posts) - Fix JS true/false -> Python True/False in code blocks - Fix parameter names: branchName->branch_slug, username->user_slug, postId->post_id - Add missing lastEvaluatedKey param docs for list jobs - Note post.listpublic as unauthenticated endpoint - Fix pagination examples (LastEvaluatedKey, not ExclusiveStartKey dict) - Remove non-existent headers param from make_request example - Fix branch.listbyname example (takes no name arg) - Add 4 missing wrapper docs: follow, react, trust, votecast - Fix broken internal links (case-sensitive filenames) - Fix <environment>_handle_token template artifact - Add CODE_BUGS.md documenting 4 code bugs found during audit
This commit is contained in:
BarnacleBoy
parent
c8611a7b88
commit
a223bcb27a
9 changed files with 552 additions and 247 deletions
214
docs/WRAPPERS.md
214
docs/WRAPPERS.md
|
|
@ -7,6 +7,7 @@ This guide covers the high-level wrapper functions provided by the TrustCafé AP
|
|||
- [Overview](#overview)
|
||||
- [Post Wrappers](#post-wrappers)
|
||||
- [Comment Wrappers](#comment-wrappers)
|
||||
- [Interaction Wrappers](#interaction-wrappers)
|
||||
- [Wrappers Best Practices](#wrappers-best-practices)
|
||||
- [Wrapper vs Job](#wrapper-vs-job)
|
||||
|
||||
|
|
@ -308,6 +309,201 @@ API.wrapped(create_comment(
|
|||
))
|
||||
```
|
||||
|
||||
## Interaction Wrappers
|
||||
|
||||
### follow()
|
||||
|
||||
Follow or unfollow a user or branch.
|
||||
|
||||
```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 to follow: `"userprofile"` or `"subwiki"` |
|
||||
| `is_following` | bool | **Required** | `True` to follow, `False` to unfollow |
|
||||
| `parent_slug` | str | **Required** | Slug of the entity to follow/unfollow |
|
||||
|
||||
**Returns:** dict - Job execution result
|
||||
|
||||
**Example - Follow a user:**
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.follow.follow import follow
|
||||
|
||||
API.wrapped(follow(
|
||||
entity="userprofile",
|
||||
is_following=True,
|
||||
parent_slug="philosopher-jon"
|
||||
))
|
||||
```
|
||||
|
||||
**Example - Unfollow a branch:**
|
||||
|
||||
```python
|
||||
API.wrapped(follow(
|
||||
entity="subwiki",
|
||||
is_following=False,
|
||||
parent_slug="music"
|
||||
))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### react()
|
||||
|
||||
React to a post or comment (like, heart, etc.). This single endpoint handles creating, updating, and deleting reactions — the logic is handled server-side.
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.reaction.react import react
|
||||
|
||||
API.wrapped(react(
|
||||
reaction_type="like",
|
||||
parent_path="/music",
|
||||
item_path="/music/my-post-slug"
|
||||
))
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `reaction_type` | str | **Required** | Reaction type (e.g., `"like"`, `"heart"`, `"fire"`) |
|
||||
| `parent_path` | str | `None` | Parent path (e.g., `"/music"`) |
|
||||
| `item_path` | str | `None` | Item path (e.g., `"/music/my-post-slug"`) |
|
||||
| `item_key` | dict | `None` | Dict with `pk` and `sk` keys |
|
||||
|
||||
**Returns:** dict - Job execution result
|
||||
|
||||
**Note:** You must provide either:
|
||||
- Both `parent_path` and `item_path`, or
|
||||
- The `item_key` dict with `pk` and `sk`
|
||||
|
||||
**Example - React by paths:**
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.reaction.react import react
|
||||
|
||||
API.wrapped(react(
|
||||
reaction_type="like",
|
||||
parent_path="/music",
|
||||
item_path="/music/my-post-slug"
|
||||
))
|
||||
```
|
||||
|
||||
**Example - React by key:**
|
||||
|
||||
```python
|
||||
API.wrapped(react(
|
||||
reaction_type="heart",
|
||||
item_key={
|
||||
"pk": "post#my-post-slug",
|
||||
"sk": "post#my-post-slug"
|
||||
}
|
||||
))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### trust()
|
||||
|
||||
Set trust level for a user profile.
|
||||
|
||||
```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: `"trusted"`, `"neutral"`, or `"distrusted"` |
|
||||
| `userprofile_path` | str | **Required** | Path to the user profile (e.g., `"/userprofile/slug"`) |
|
||||
|
||||
**Returns:** dict - Job execution result
|
||||
|
||||
**Example:**
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.trust.trust import trust
|
||||
|
||||
API.wrapped(trust(
|
||||
trustLevel="trusted",
|
||||
userprofile_path="/userprofile/philosopher-jon"
|
||||
))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### votecast()
|
||||
|
||||
Cast a vote on a post or comment.
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.vote.votecast import votecast
|
||||
|
||||
API.wrapped(votecast(
|
||||
vote="up",
|
||||
parent_path="/music",
|
||||
item_path="/music/my-post-slug"
|
||||
))
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `vote` | str | **Required** | Vote value (e.g., `"up"`, `"down"`) |
|
||||
| `parent_path` | str | `None` | Parent path |
|
||||
| `item_path` | str | `None` | Item path |
|
||||
| `item_key` | dict | `None` | Dict with `pk` and `sk` keys |
|
||||
|
||||
**Returns:** dict - Job execution result
|
||||
|
||||
**Note:** You must provide either:
|
||||
- Both `parent_path` and `item_path`, or
|
||||
- The `item_key` dict with `pk` and `sk`
|
||||
|
||||
**Example - Vote by paths:**
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.vote.votecast import votecast
|
||||
|
||||
API.wrapped(votecast(
|
||||
vote="up",
|
||||
parent_path="/music",
|
||||
item_path="/music/my-post-slug"
|
||||
))
|
||||
```
|
||||
|
||||
**Example - Vote by key:**
|
||||
|
||||
```python
|
||||
API.wrapped(votecast(
|
||||
vote="down",
|
||||
item_key={
|
||||
"pk": "post#my-post-slug",
|
||||
"sk": "post#my-post-slug"
|
||||
}
|
||||
))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Wrappers Best Practices
|
||||
|
||||
### 1. Provide Context in Parent Paths
|
||||
|
|
@ -358,16 +554,20 @@ It's good practice to verify the parent path exists:
|
|||
|
||||
```python
|
||||
# Check if branch exists
|
||||
branches = API.run_job('branch.listbyname', "music")
|
||||
branches = API.run_job('branch.listbyname')
|
||||
|
||||
if branches.get('Items'):
|
||||
# Branch exists, proceed with post
|
||||
API.wrapped(create_post(
|
||||
"Content",
|
||||
parent_path="/music"
|
||||
))
|
||||
branch_slugs = [b.get('slug') for b in branches.get('Items', [])]
|
||||
if 'music' in branch_slugs:
|
||||
# Branch exists, proceed with post
|
||||
API.wrapped(create_post(
|
||||
"Content",
|
||||
parent_path="/music"
|
||||
))
|
||||
else:
|
||||
print("Branch 'music' does not exist")
|
||||
else:
|
||||
print("Branch 'music' does not exist")
|
||||
print("No branches found")
|
||||
```
|
||||
|
||||
### 5. Handle Responses
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue