docs(xchat): correct chat-xdk SDK API surface across guides - #255
Closed
santiagomed wants to merge 6 commits into
Closed
docs(xchat): correct chat-xdk SDK API surface across guides#255santiagomed wants to merge 6 commits into
santiagomed wants to merge 6 commits into
Conversation
…sync Replaces the branch's 21-commit history (which included an accidental site-wide content overlay later reverted) with the intended content re-applied on current main: - xchat/ guide pages (introduction, cryptography primer, getting started, XDK reference, media, groups, real-time events, troubleshooting) carried over from the previous branch head - Chat API product navigation spliced into docs.json (additive only) - openapi.json synced verbatim from the live https://api.x.com/2/openapi.json, which now serves the chat action-signature, error-message, and public-key contract updates
…ract changes Reflect the current Chat API and Chat XDK surface: - conversation-key setup now uses prepare_conversation_key_change (one call: fresh key + participant wraps + signed action signature); the keys endpoint adds or rotates keys and returns the canonical conversation_id alongside sequence_id - group creation uses prepare_group_create and member adds use prepare_group_members_change; both return two action signatures and the docs show sending both - action signatures are required and validated at the API boundary (400 problem-details on malformed input); group endpoints return stable human-readable error messages - public-key responses name the version field public_key_version; every fields list and sample read updated - removed dropped SDK methods (prepare_conversation_keys, sign_add_members, sign_key_change, encrypt_conversation_key_for_recipients) and renamed PreparedConversationKeys to PreparedConversationChange - documented conversation-id form flexibility (colon, hyphen, or bare recipient id all sign identically; URL paths still use hyphens), permanent verification failures, and chunked stream encryption
- teach verify_key_binding before wrapping conversation keys (warnings in Getting Started and the XDK reference, step in Groups) - state the group title/avatar verbatim-match rule: values passed to prepare_group_create are signed and embedded exactly as given, so the POST body must carry byte-identical group_name/group_avatar_url; the encrypted-metadata section explains why a create-time title cannot be ciphertext under the group's own key - point group flows at the batch public-keys route - add rotation semantics: fresh keys on member adds mean new members cannot read earlier versions, rotation never revokes old versions, and rotating after suspected exposure protects future messages only - primer: new 'Signed state changes (action signatures)' section covering what is signed, why the server validates structurally, and where cryptographic verification happens - fix encrypt_reply samples to the real positional signatures and encrypt_message optional-argument names - replace every ellipsis with explicit paths, field lists, example values, or complete code
Fix API-accuracy bugs against the current SDK: streaming is a two-arg raw-bytes call (media_hash_key comes from upload finalize, not encrypt_stream); prepare methods take a single params object/struct in every binding except Python (and the params types dropped the Prepare prefix); decrypt_events .errors is a map, not a list; Go conversation keys are raw bytes, not base64; verification is fail-closed by default. Add the incremental streaming API, the keyVersion-per-event media key selection contract, the three Juicebox config shapes, and the hex utility helpers.
Address code-review findings on the API-accuracy pass: TypeScript encrypt_message/encrypt_reply/reactions take a single params object; Go import_keys takes raw bytes (decode the base64 env var first); Go utility calls honor their (value, error) arities; Java reads the public conversationKey field, not a getter; C#/Java/Rust image-dimension and conversation-key types match the SDK; width/height casts added where narrowing.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Collaborator
Author
|
Superseded by #256, which targets the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Corrects API-accuracy bugs in the X Chat SDK guides (
xchat/*.mdx) against the current chat-xdk SDK. Several examples were copy-paste-and-it-breaks; this makes every language tab match the shipped API.Bugs fixed
encrypt_stream/decrypt_streamare two-arg, raw-bytes calls — the docs showed a{ciphertext, media_hash_key}return and a 3-arg decrypt.media_hash_keycomes from the media-upload finalize step, notencrypt_stream.Prepareprefix (PrepareGroupCreateParams→GroupCreateParams).encrypt_message/encrypt_reply/reactions: TypeScript tabs used positional args; the WASM binding takes a params object (reply usesreplyToSequenceId).decrypt_events.errorsis a map{ index → message }, not a list — the JSfor…ofwould throw.[]byte, not base64 strings (base64 is an internal FFI detail); GoImportKeystakes[]byte; Go utility calls honor their(value, error)arities.conversationKeyfield (no getter); C#/Java/Rust image-dimension and conversation-key types corrected (ImageDimensions,Option<XChatConversationKey>+.to_bytes(),&XChatConversationKeyfor stream/encrypt/decrypt).set_reject_unverified(true)is how you fail closed. Corrected: verification is mandatory unless you callset_reject_unverified(false).Gaps added
stream_encryptor/stream_decryptor, push/finish, ~1 MB chunks, JS "neverfree()afterfinish()").keyVersion-per-event → media key selection contract (decrypt old media with the key of that event's version after a rotation).Verification
Every signature verified against the SDK source (
index.d.ts,__init__.pyi,go/chatxdk,Chat.cs/Types.cs,Chat.java/Types.java,core.rs/params.rs/utils.rs,keys/juicebox.rs). Ran a reviewer pass; applied all valid findings (one "only two juicebox shapes" finding was rejected — verified #114 landed the thirdkey_store_token_map_jsonbranch). All<Tabs>/<Tab>blocks balanced.