docs: update README, examples, and docs for recent API features

[tirthpatell]

Summary

• README: Add missing feature docs (GIF posts, ghost posts, reply approvals, ContainerBuilder, IsTransientError), fix 3 incorrect code examples, mark as unofficial, add Go version note
• Examples: Fix non-existent QuotePostContent type, wrong CreateQuotePost/RepostPost signatures, wrong env var in .env.example; add GIF, ghost post, and reply approval examples
• CI: Scope coverage to library package only via -coverpkg (fixes badge: 34.8% -> 51.3%)
• LICENSE: Update copyright to 2024-present
• CONTRIBUTING: Add Go version range, add go test -race command

Bugs fixed in docs

File	Bug
README.md	ExchangeCodeForToken / GetLongLivedToken missing ctx param
README.md	GetUserPosts using PostsOptions instead of PaginationOptions
examples/basic-usage/main.go	References non-existent QuotePostContent type
examples/post-creation/main.go	Wrong CreateQuotePost(content) signature
examples/post-creation/main.go	Wrong RepostPost(postIDToRepost) signature
examples/.env.example	DEBUG instead of THREADS_DEBUG

Test plan

• All examples compile: go build ./examples/...
• Unit tests pass with new coverage flag: go test -short -race -coverpkg=github.com/tirthpatell/threads-go ./...
• Coverage correctly reports 51.3% (library only, excludes examples)

[greptile-apps]

Greptile Summary

This PR fixes several concrete bugs in the documentation and examples — incorrect function signatures, non-existent types, and wrong environment variable names — and adds documentation for newer API features (GIF posts, ghost posts, reply approvals, ContainerBuilder, IsTransientError). All new code examples were cross-checked against the library source and are accurate.

Key fixes verified correct:

• ExchangeCodeForToken / GetLongLivedToken now include the missing ctx parameter
• GetUserPosts now uses PaginationOptions instead of the non-existent PostsOptions override
• examples/basic-usage/main.go no longer references the non-existent QuotePostContent type — correctly replaced with TextPostContent + QuotedPostID
• CreateQuotePost and RepostPost signatures in examples/post-creation/main.go now match the actual library API
• examples/.env.example corrects DEBUG → THREADS_DEBUG
• NewContainerBuilder() is called with zero arguments (fixing the previously flagged bug)
• ReplyControlFollowersOnly is used (valid constant; the previously flagged ReplyControlFollowing is gone)

CI change: -coverpkg=github.com/tirthpatell/threads-go correctly scopes coverage to the library package, preventing example binaries and integration stubs from diluting the reported percentage.

Style observations:

• createGIFPost and createGhostPost in examples/post-creation/main.go accept a named client *threads.Client parameter that is never used, inconsistent with the _ *threads.Client convention used by every other dry-run function in the file (createCarouselPost, createQuotePost, createRepost)
• The ContainerBuilder README snippet passes a raw string "TEXT" to SetMediaType, while the library exports threads.MediaTypeText for this purpose

Confidence Score: 4/5

• Safe to merge — all code changes are in documentation and examples; no library logic is modified and all new snippets compile correctly against the actual API surface.
• All fixed examples were verified against the library source (types.go, posts_create.go, replies.go, container_builder.go, errors.go). The new API feature snippets (GIF, ghost posts, reply approvals, ContainerBuilder) reference only existing types and methods. The CI change is a straightforward scope flag with no behavioral risk. The two open points are purely stylistic (unused named parameter, raw string vs. constant) and do not affect correctness or compilation.
• examples/post-creation/main.go — minor inconsistency in unused parameter naming for the two new example functions

Important Files Changed

Filename	Overview
README.md	Fixes several incorrect code examples (missing ctx params, wrong options type, non-existent QuotePostContent), adds documentation for GIF posts, ghost posts, reply approvals, ContainerBuilder, and IsTransientError. One style issue: ContainerBuilder example uses raw string "TEXT" instead of threads.MediaTypeText.
examples/post-creation/main.go	Fixes wrong CreateQuotePost and RepostPost signatures, adds GIF and ghost post example functions. New createGIFPost and createGhostPost use named client parameter instead of the _ blank identifier convention used by all other dry-run functions in the file.
examples/reply-management/main.go	Adds demonstrateReplyApprovals function showing ApprovePendingReply and IgnorePendingReply usage. Correctly uses _ *threads.Client and accurately documents the API surface.
examples/basic-usage/main.go	Fixes non-existent QuotePostContent reference, replacing it with the correct TextPostContent with QuotedPostID field. No issues found.
.github/workflows/ci.yml	Adds -coverpkg=github.com/tirthpatell/threads-go flag to scope coverage reporting to the library package only, correctly fixing the inflated/deflated badge percentage. No issues found.
CONTRIBUTING.md	Adds -short flag to test commands and clarifies integration test separation. The integration tests use a //go:build integration build tag, so go test -short -race ./... will not include them regardless.
examples/.env.example	Fixes wrong environment variable name from DEBUG to THREADS_DEBUG. Correct fix.
examples/README.md	Updates example index to document new GIF posts, ghost posts, and reply approvals examples. Accurate and complete.
LICENSE	Updates copyright year from 2024 to 2024-present. Correct change.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User reads README or examples] --> B{Which API feature?}

    B --> C[Post Creation]
    B --> D[GIF Posts]
    B --> E[Ghost Posts]
    B --> F[Reply Approvals]
    B --> G[ContainerBuilder]

    C --> C1["CreateTextPost(ctx, &TextPostContent{...})"]
    C --> C2["CreateImagePost / CreateVideoPost / CreateCarouselPost"]
    C --> C3["CreateTextPost with QuotedPostID for quotes"]
    C --> C4["RepostPost(ctx, threads.PostID(...))"]

    D --> D1["TextPostContent{ GIFAttachment: &GIFAttachment{GIFID, GIFProviderGiphy} }"]

    E --> E1["TextPostContent{ IsGhostPost: true }"]
    E --> E2["GetUserGhostPosts(ctx, userID, nil)"]

    F --> F1["TextPostContent{ EnableReplyApprovals: true }"]
    F --> F2["ApprovePendingReply(ctx, PostID)"]
    F --> F3["IgnorePendingReply(ctx, PostID)"]

    G --> G1["NewContainerBuilder()"]
    G1 --> G2[".SetMediaType / .SetText / .SetReplyControl / ..."]
    G2 --> G3[".Build() → url.Values"]

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: examples/post-creation/main.go
Line: 294

Comment:
**Unused named parameter inconsistent with existing pattern**

`createGIFPost` (and `createGhostPost` below) accept a named `client *threads.Client` parameter that is never referenced in the function body. Every other dry-run function in this file uses `_ *threads.Client` to signal intentional non-use:

- `createCarouselPost(_ *threads.Client)` (line 200)
- `createQuotePost(_ *threads.Client)` (line 240)
- `createRepost(_ *threads.Client)` (line 271)

While Go does not produce a compile error for unused function parameters, the inconsistency breaks the established convention in the file and could confuse readers who expect the `client` variable to be used somewhere. The same applies to `createGhostPost` at line 323.

```suggestion
func createGIFPost(_ *threads.Client) {
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: examples/post-creation/main.go
Line: 323

Comment:
**Unused named parameter inconsistent with existing pattern**

Same issue as `createGIFPost`: the `client` parameter is named but never used. For consistency with the other dry-run helpers in this file, it should be replaced with the blank identifier.

```suggestion
func createGhostPost(_ *threads.Client) {
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: README.md
Line: 215

Comment:
**Raw string instead of exported constant**

`SetMediaType("TEXT")` passes a magic string that readers must know matches the library's internal expectation. The library exports `threads.MediaTypeText` (and `threads.MediaTypeImage`, `threads.MediaTypeVideo`, `threads.MediaTypeCarousel`) in `constants.go` specifically to avoid this pattern. Using the constant also makes the example self-consistent with how the library is used internally (e.g., in `container_builder.go`).

```suggestion
builder := threads.NewContainerBuilder().
    SetMediaType(threads.MediaTypeText).
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: 799f568}