@volter/twin-x 0.1.0

package/src/x-conformance.ts

@@ -0,0 +1,113 @@
+// Spec conformance for the X posting surface — dev-only, imported LAZILY by cli.ts so it never
+// enters the pack's runtime entrypoint graph.
+//
+// What it checks is what a client's own code depends on and a status-only check would miss: the
+// vendor's response SHAPES (create is thin, the mentions timeline OMITS `data` when empty), and
+// the negative paths (a bad bearer is the about:blank problem, an unmodelled /2 route is a 404
+// problem, a reply to a post that does not exist is `resource-not-found`).
+import { handleXTwinRequest } from './x-twin.ts';
+
+export type XConformanceReport = { ok: boolean; checksRun: number; failures: string[] };
+
+export async function checkXConformance(options: { root?: string } = {}): Promise<XConformanceReport> {
+  const failures: string[] = [];
+  const check = (name: string, ok: boolean) => { if (!ok) failures.push(name); };
+  const root = options.root;
+  const auth = { authorization: 'Bearer conformance-token' };
+  const h = (method: string, path: string, body?: unknown, headers: Record<string, string> = auth) =>
+    handleXTwinRequest({ method, path, headers, root, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+
+  await h('POST', '/_twin/accounts', { id: '1000', username: 'orgvoice', name: 'Org Voice' }, {});
+  await h('POST', '/_twin/accounts', { id: '2000', username: 'member' }, {});
+  await h('POST', '/_twin/tokens', { token: 'conformance-token', account_id: '1000', scopes: ['tweet.read', 'tweet.write', 'users.read'] }, {});
+
+  const created = await h('POST', '/2/tweets', { text: 'hello world' });
+  const createdBody = created.body as any;
+  check('create answers 201 with the thin {id, text, edit_history_tweet_ids} data envelope', created.status === 201
+    && typeof createdBody?.data?.id === 'string'
+    && createdBody.data.text === 'hello world'
+    && Array.isArray(createdBody.data.edit_history_tweet_ids)
+    && createdBody.data.edit_history_tweet_ids[0] === createdBody.data.id
+    && Object.keys(createdBody.data).length === 3);
+
+  const emptyMentions = await h('GET', '/2/users/1000/mentions');
+  check('an EMPTY mentions timeline omits `data` and answers with meta.result_count 0', emptyMentions.status === 200
+    && (emptyMentions.body as any)?.meta?.result_count === 0
+    && (emptyMentions.body as any)?.data === undefined);
+
+  await h('POST', '/_twin/posts', { author_id: '2000', text: 'hey @orgvoice can you help' }, {});
+  const mentions = await h('GET', '/2/users/1000/mentions');
+  const mentionsBody = mentions.body as any;
+  check('a mentions timeline carries data[] plus meta.newest_id/oldest_id', mentions.status === 200
+    && Array.isArray(mentionsBody?.data) && mentionsBody.data.length === 1
+    && mentionsBody.meta?.result_count === 1
+    && mentionsBody.meta?.newest_id === mentionsBody.data[0].id
+    && mentionsBody.meta?.oldest_id === mentionsBody.data[0].id);
+
+  const replied = await h('POST', '/2/tweets', { text: 'happy to help', reply: { in_reply_to_tweet_id: mentionsBody.data[0].id } });
+  check('a reply answers 201 with the same thin envelope a post does', replied.status === 201 && typeof (replied.body as any)?.data?.id === 'string');
+
+  const deleted = await h('DELETE', `/2/tweets/${(replied.body as any).data.id}`);
+  check('delete answers {data:{deleted:true}}', deleted.status === 200 && (deleted.body as any)?.data?.deleted === true);
+
+  const noAuth = await h('GET', '/2/users/1000/mentions', undefined, {});
+  check('an absent bearer is the about:blank 401 problem', noAuth.status === 401
+    && (noAuth.body as any)?.type === 'about:blank'
+    && (noAuth.body as any)?.title === 'Unauthorized');
+
+  const unmodelled = await h('GET', '/2/tweets/counts/recent?query=x');
+  check('an UNMODELLED /2 route fails like the vendor (404 problem), never a fake success', unmodelled.status === 404
+    && (unmodelled.body as any)?.title === 'Not Found Error');
+
+  const orphanReply = await h('POST', '/2/tweets', { text: 'to nobody', reply: { in_reply_to_tweet_id: '404404404404404404' } });
+  check('a reply to a post that does not exist is the resource-not-found problem', orphanReply.status === 404
+    && (orphanReply.body as any)?.errors?.[0]?.resource_type === 'tweet'
+    && (orphanReply.body as any)?.errors?.[0]?.parameter === 'reply.in_reply_to_tweet_id');
+
+  const noText = await h('POST', '/2/tweets', {});
+  check('a create with no text is the invalid-request problem', noText.status === 400
+    && (noText.body as any)?.type === 'https://api.x.com/2/problems/invalid-request');
+
+  const looked = await h('GET', `/2/tweets/${createdBody.data.id}`);
+  check('post lookup answers the DEFAULT projection — id, text, edit_history_tweet_ids and nothing else', looked.status === 200
+    && Object.keys((looked.body as any)?.data ?? {}).sort().join(',') === 'edit_history_tweet_ids,id,text'
+    && (looked.body as any).data.id === createdBody.data.id);
+
+  const projected = await h('GET', `/2/tweets/${createdBody.data.id}?tweet.fields=author_id,conversation_id`);
+  check('tweet.fields adds exactly the fields asked for', projected.status === 200
+    && (projected.body as any)?.data?.author_id === '1000'
+    && (projected.body as any).data.conversation_id === createdBody.data.id);
+
+  const ghost = await h('GET', '/2/tweets/404404404404404404');
+  check('a lookup of an id nobody created answers `errors`, never a fabricated `data`', ghost.status === 200
+    && (ghost.body as any)?.data === undefined
+    && (ghost.body as any)?.errors?.[0]?.resource_type === 'tweet'
+    && (ghost.body as any).errors[0].value === '404404404404404404');
+
+  const bulk = await h('GET', `/2/tweets?ids=${createdBody.data.id},404404404404404404`);
+  check('a bulk lookup is PARTIAL: the id that exists in data, the one that does not in errors', bulk.status === 200
+    && (bulk.body as any)?.data?.length === 1
+    && (bulk.body as any).data[0].id === createdBody.data.id
+    && (bulk.body as any)?.errors?.length === 1);
+
+  const own = await h('GET', '/2/users/1000/tweets');
+  check("the author's own timeline carries the post it made", own.status === 200
+    && ((own.body as any)?.data ?? []).some((row: any) => row.id === createdBody.data.id));
+
+  const searched = await h('GET', '/2/tweets/search/recent?query=hello');
+  const searchUnsupported = await h('GET', '/2/tweets/search/recent?query=hello OR world');
+  check('recent search matches on the stored text, and refuses grammar the twin does not model', searched.status === 200
+    && ((searched.body as any)?.data ?? []).some((row: any) => row.id === createdBody.data.id)
+    && searchUnsupported.status === 400
+    && (searchUnsupported.body as any)?.errors?.[0]?.parameters?.query?.[0] === 'OR');
+
+  const foreignHome = await h('GET', '/2/users/2000/timelines/reverse_chronological');
+  check("the home timeline is refused for an account that is not the bearer's", foreignHome.status === 403
+    && (foreignHome.body as any)?.title === 'Forbidden');
+
+  const tooLong = await h('POST', '/2/tweets', { text: 'x'.repeat(281) });
+  check('a post over the account character limit is the invalid-request problem', tooLong.status === 400
+    && (tooLong.body as any)?.errors?.[0]?.parameters?.text?.[0] === '281');
+
+  return { ok: failures.length === 0, checksRun: 18, failures };
+}