feat: API conformance audit — align client with official Threads API docs (#24)

Author: tirthpatell

README.md

@@ -67,6 +67,18 @@ err = client.ExchangeCodeForToken(ctx, "auth-code-from-callback")
 err = client.GetLongLivedToken(ctx) // Convert to long-lived token
 ```
 
+### App Access Tokens
+
+For APIs that require app-level auth instead of user tokens (e.g., oEmbed):
+
+```go
+// Full API call (server-side only — exposes app secret)
+tokenResp, err := client.GetAppAccessToken(ctx)
+
+// Or use the shorthand format (no API call needed)
+shorthand := client.GetAppAccessTokenShorthand() // "TH|<APP_ID>|<APP_SECRET>"
+```
+
 ### Environment Variables
 
 ```bash
@@ -111,7 +123,7 @@ post, err := client.GetPost(ctx, threads.PostID("123"))
 posts, err := client.GetUserPosts(ctx, threads.UserID("456"), &threads.PaginationOptions{Limit: 25})
 
 // Delete post
-err = client.DeletePost(ctx, threads.PostID("123"))
+deletedID, err := client.DeletePost(ctx, threads.PostID("123"))
 ```
 
 ### Users & Profiles

auth.go

@@ -31,6 +31,13 @@ type LongLivedTokenResponse struct {
 	ExpiresIn   int64  `json:"expires_in"`
 }
 
+// AppAccessTokenResponse represents the response from the client_credentials token endpoint.
+// Unlike user token responses, app access tokens do not include expires_in or user_id fields.
+type AppAccessTokenResponse struct {
+	AccessToken string `json:"access_token"`
+	TokenType   string `json:"token_type"`
+}
+
 // generateState generates a random state parameter for OAuth security
 func generateState() (string, error) {
 	b := make([]byte, 32)
@@ -469,6 +476,54 @@ func (c *Client) DebugToken(ctx context.Context, inputToken string) (*DebugToken
 	return &debugResp, nil
 }
 
+// GetAppAccessToken generates an app access token via the client_credentials OAuth flow.
+// Unlike user access tokens, the returned token is NOT stored in the client — app tokens
+// serve a different purpose and should be managed separately by the caller.
+// This requires ClientID and ClientSecret to be set in the client configuration.
+//
+// NOTE: The Threads API requires GET for this endpoint (not the POST + body
+// approach specified in RFC 6749 §4.4). As a result, client_secret appears in
+// the request URL. Only call this from a server-side environment.
+func (c *Client) GetAppAccessToken(ctx context.Context) (*AppAccessTokenResponse, error) {
+	params := url.Values{
+		"client_id":     {c.config.ClientID},
+		"client_secret": {c.config.ClientSecret},
+		"grant_type":    {"client_credentials"},
+	}
+
+	resp, err := c.httpClient.GET("/oauth/access_token", params, "")
+	if err != nil {
+		return nil, NewNetworkError(0, "Failed to get app access token", err.Error(), true)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, c.handleTokenError(resp.StatusCode, resp.Body)
+	}
+
+	var tokenResp AppAccessTokenResponse
+	if err := json.Unmarshal(resp.Body, &tokenResp); err != nil {
+		return nil, NewAPIError(resp.StatusCode, "Failed to parse app access token response", err.Error(), "")
+	}
+
+	if c.config.Logger != nil {
+		c.config.Logger.Info("Successfully obtained app access token",
+			"token_type", tokenResp.TokenType)
+	}
+
+	return &tokenResp, nil
+}
+
+// GetAppAccessTokenShorthand returns the shorthand app token in the form TH|<APP_ID>|<APP_SECRET>.
+// This can be used directly as an access token for certain API operations without making an API call.
+// See the Threads API documentation for which endpoints accept this format.
+// Returns an empty string if ClientID or ClientSecret are not configured.
+func (c *Client) GetAppAccessTokenShorthand() string {
+	if c.config.ClientID == "" || c.config.ClientSecret == "" {
+		return ""
+	}
+	return "TH|" + c.config.ClientID + "|" + c.config.ClientSecret
+}
+
 // SetTokenFromDebugInfo creates and sets token info from debug token response.
 // This method takes the response from the debug_token endpoint and creates a properly
 // configured TokenInfo struct with accurate expiration times based on the API response.

auth_test.go

@@ -656,6 +656,138 @@ func TestSetTokenFromDebugInfo_WithLogger(t *testing.T) {
 	}
 }
 
+func TestGetAppAccessToken_Success(t *testing.T) {
+	handler := func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "GET" {
+			http.NotFound(w, r)
+			return
+		}
+		if r.URL.Path != "/oauth/access_token" {
+			http.NotFound(w, r)
+			return
+		}
+		q := r.URL.Query()
+		if q.Get("grant_type") != "client_credentials" {
+			w.WriteHeader(400)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(200)
+		_, _ = w.Write([]byte(`{"access_token":"TH|test-client-id|some_token","token_type":"bearer"}`))
+	}
+
+	server := httptest.NewServer(http.HandlerFunc(handler))
+	t.Cleanup(server.Close)
+
+	config := &Config{
+		ClientID:     "test-client-id",
+		ClientSecret: "test-client-secret",
+		RedirectURI:  "https://example.com/callback",
+	}
+	config.SetDefaults()
+	config.BaseURL = server.URL
+
+	client, err := NewClient(config)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	resp, err := client.GetAppAccessToken(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp.AccessToken != "TH|test-client-id|some_token" {
+		t.Errorf("expected TH|test-client-id|some_token, got %s", resp.AccessToken)
+	}
+	if resp.TokenType != "bearer" {
+		t.Errorf("expected bearer, got %s", resp.TokenType)
+	}
+	// App token must NOT be stored in client
+	if client.GetAccessToken() != "" {
+		t.Error("expected client access token to remain empty after GetAppAccessToken")
+	}
+}
+
+func TestGetAppAccessToken_ServerError(t *testing.T) {
+	client := testClientNoAuth(t, jsonHandler(401, `{"error":{"message":"invalid credentials","type":"OAuthException","code":100}}`))
+	_, err := client.GetAppAccessToken(context.Background())
+	if err == nil {
+		t.Fatal("expected error for server error response")
+	}
+}
+
+func TestGetAppAccessToken_ParseError(t *testing.T) {
+	client := testClientNoAuth(t, jsonHandler(200, `not valid json`))
+	_, err := client.GetAppAccessToken(context.Background())
+	if err == nil {
+		t.Fatal("expected error for invalid JSON response")
+	}
+}
+
+func TestGetAppAccessToken_WithLogger(t *testing.T) {
+	handler := jsonHandler(200, `{"access_token":"TH|id|tok","token_type":"bearer"}`)
+	config := testClientConfig(t, handler)
+	config.Logger = &noopLogger{}
+	client, err := NewClient(config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp, err := client.GetAppAccessToken(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp.AccessToken != "TH|id|tok" {
+		t.Errorf("expected TH|id|tok, got %s", resp.AccessToken)
+	}
+}
+
+func TestGetAppAccessTokenShorthand(t *testing.T) {
+	config := &Config{
+		ClientID:     "my-app-123",
+		ClientSecret: "my-secret-abc",
+		RedirectURI:  "https://example.com/callback",
+	}
+	config.SetDefaults()
+	client, err := NewClient(config)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	shorthand := client.GetAppAccessTokenShorthand()
+	expected := "TH|my-app-123|my-secret-abc"
+	if shorthand != expected {
+		t.Errorf("expected %q, got %q", expected, shorthand)
+	}
+}
+
+func TestGetAppAccessTokenShorthand_Format(t *testing.T) {
+	config := &Config{
+		ClientID:     "appid",
+		ClientSecret: "appsecret",
+		RedirectURI:  "https://example.com/callback",
+	}
+	config.SetDefaults()
+	client, err := NewClient(config)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	shorthand := client.GetAppAccessTokenShorthand()
+	if !strings.HasPrefix(shorthand, "TH|") {
+		t.Errorf("expected shorthand to start with TH|, got %q", shorthand)
+	}
+	parts := strings.Split(shorthand, "|")
+	if len(parts) != 3 {
+		t.Errorf("expected 3 pipe-separated parts, got %d: %q", len(parts), shorthand)
+	}
+	if parts[1] != "appid" {
+		t.Errorf("expected app ID appid in shorthand, got %q", parts[1])
+	}
+	if parts[2] != "appsecret" {
+		t.Errorf("expected app secret appsecret in shorthand, got %q", parts[2])
+	}
+}
+
 func TestTokenExpiration(t *testing.T) {
 	config := &Config{
 		ClientID:     "test-id",

constants.go

@@ -25,11 +25,19 @@ const (
 	// Reply processing
 	ReplyPublishDelay = 10 * time.Second // Recommended delay before publishing reply
 
+	// Poll limits
+	MinPollOptions      = 2  // Minimum poll options (A and B required)
+	MaxPollOptions      = 4  // Maximum poll options
+	MaxPollOptionLength = 25 // Maximum characters per poll option
+
+	// Alt text limits
+	MaxAltTextLength = 1000 // Maximum characters for alt text
+
 	// Search constraints
 	MinSearchTimestamp = 1688540400 // Minimum timestamp for search queries (July 5, 2023)
 
 	// Library version
-	Version = "1.1.0"
+	Version = "1.8.0"
 
 	// HTTP client defaults
 	DefaultHTTPTimeout = 30 * time.Second // Default HTTP request timeout
@@ -44,7 +52,7 @@ const (
 // Field Sets for API requests
 const (
 	// Post fields
-	PostExtendedFields = "id,media_product_type,media_type,media_url,permalink,owner,username,text,timestamp,shortcode,thumbnail_url,children,is_quote_post,alt_text,link_attachment_url,has_replies,reply_audience,quoted_post,reposted_post,gif_url,is_verified,profile_picture_url"
+	PostExtendedFields = "id,media_product_type,media_type,media_url,permalink,owner,username,text,timestamp,shortcode,thumbnail_url,children,is_quote_post,alt_text,link_attachment_url,has_replies,reply_audience,quoted_post,reposted_post,gif_url,is_verified,profile_picture_url,poll_attachment,topic_tag,is_spoiler_media,text_entities,text_attachment,location_id,location,allowlisted_country_codes,ghost_post_status,ghost_post_expiration_timestamp,is_reply,root_post,replied_to,is_reply_owned_by_me,hide_status,reply_approval_status"
 
 	// Ghost Post fields
 	GhostPostFields = "id,media_product_type,media_type,media_url,permalink,owner,username,text,timestamp,shortcode,thumbnail_url,ghost_post_status,ghost_post_expiration_timestamp"
@@ -62,7 +70,7 @@ const (
 	LocationFields = "id,address,name,city,country,latitude,longitude,postal_code"
 
 	// Publishing limit fields
-	PublishingLimitFields = "quota_usage,config,reply_quota_usage,reply_config,delete_quota_usage,delete_config,location_search_quota_usage,location_search_config"
+	PublishingLimitFields = "quota_usage,config,reply_quota_usage,reply_config,delete_quota_usage,delete_config,location_search_quota_usage,location_search_config,search_quota_usage,search_config"
 )
 
 // Container Status values
@@ -84,6 +92,26 @@ const (
 	MediaTypeImage    = "IMAGE"
 	MediaTypeVideo    = "VIDEO"
 	MediaTypeCarousel = "CAROUSEL"
+
+	// Response media types (returned by the API when retrieving posts)
+	MediaTypeResponseText     = "TEXT_POST"
+	MediaTypeResponseCarousel = "CAROUSEL_ALBUM"
+	MediaTypeAudio            = "AUDIO"
+	MediaTypeRepostFacade     = "REPOST_FACADE"
+)
+
+// Container error messages returned by the API
+const (
+	ContainerErrFailedDownloadingVideo    = "FAILED_DOWNLOADING_VIDEO"
+	ContainerErrFailedProcessingAudio     = "FAILED_PROCESSING_AUDIO"
+	ContainerErrFailedProcessingVideo     = "FAILED_PROCESSING_VIDEO"
+	ContainerErrInvalidAspectRatio        = "INVALID_ASPEC_RATIO" // Note: API has typo "ASPEC"
+	ContainerErrInvalidBitRate            = "INVALID_BIT_RATE"
+	ContainerErrInvalidDuration           = "INVALID_DURATION"
+	ContainerErrInvalidFrameRate          = "INVALID_FRAME_RATE"
+	ContainerErrInvalidAudioChannels      = "INVALID_AUDIO_CHANNELS"
+	ContainerErrInvalidAudioChannelLayout = "INVALID_AUDIO_CHANNEL_LAYOUT"
+	ContainerErrUnknown                   = "UNKNOWN"
 )
 
 // Error messages
@@ -100,4 +128,12 @@ const (
 	// This error occurs during media container creation (POST /{threads-user-id}/threads).
 	// Reduce the number of unique links to 5 or fewer to resolve.
 	ErrCodeLinkLimitExceeded = "THREADS_API__LINK_LIMIT_EXCEEDED"
+
+	// ErrCodeFeatureNotAvailable is returned when a feature is not available for the user.
+	// For example, geo-gating requires feature approval before it can be used.
+	ErrCodeFeatureNotAvailable = "THREADS_API__FEATURE_NOT_AVAILABLE"
+
+	// ErrCodeGeoGatingInvalidCountryCodes is returned when invalid country codes
+	// are provided for geo-gated posts.
+	ErrCodeGeoGatingInvalidCountryCodes = "THREADS_API__GEO_GATING_INVALID_COUNTRY_CODES"
 )

container_builder.go

@@ -18,9 +18,14 @@ func NewContainerBuilder() *ContainerBuilder {
 	}
 }
 
-// SetMediaType sets the media type
+// SetMediaType sets the media type.
+// If a non-TEXT type is set, any previously set is_ghost_post flag is cleared
+// since ghost posts are only supported for TEXT.
 func (b *ContainerBuilder) SetMediaType(mediaType string) *ContainerBuilder {
 	b.params.Set("media_type", mediaType)
+	if mediaType != "" && mediaType != MediaTypeText {
+		b.params.Del("is_ghost_post")
+	}
 	return b
 }
 
@@ -211,10 +216,21 @@ func (b *ContainerBuilder) SetGIFAttachment(gifAttachment *GIFAttachment) *Conta
 	return b
 }
 
-// SetIsGhostPost marks the post as a ghost post (text-only, expires in 24h, no replies allowed)
+// SetIsGhostPost marks the post as a ghost post (text-only, expires in 24h, no replies allowed).
+// Ghost posts are only supported for TEXT media type. If the builder's media_type is already set
+// to a non-TEXT value this call is silently ignored; if a non-TEXT type is set after this call,
+// SetMediaType will automatically clear the flag.
 func (b *ContainerBuilder) SetIsGhostPost(isGhostPost bool) *ContainerBuilder {
 	if isGhostPost {
+		// Ghost posts are only allowed for TEXT media type
+		mediaType := b.params.Get("media_type")
+		if mediaType != "" && mediaType != MediaTypeText {
+			// Silently ignore - ghost post flag is not applicable to non-text posts
+			return b
+		}
 		b.params.Set("is_ghost_post", "true")
+	} else {
+		b.params.Del("is_ghost_post")
 	}
 	return b
 }