@volter/twin-x 0.1.0

package/dist/src/x-conformance.d.ts

@@ -0,0 +1,8 @@
+export type XConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    failures: string[];
+};
+export declare function checkXConformance(options?: {
+    root?: string;
+}): Promise<XConformanceReport>;

package/dist/src/x-conformance.js

@@ -0,0 +1,91 @@
+// 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.js";
+export async function checkXConformance(options = {}) {
+    const failures = [];
+    const check = (name, ok) => { if (!ok)
+        failures.push(name); };
+    const root = options.root;
+    const auth = { authorization: 'Bearer conformance-token' };
+    const h = (method, path, body, headers = 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;
+    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?.meta?.result_count === 0
+        && emptyMentions.body?.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;
+    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?.data?.id === 'string');
+    const deleted = await h('DELETE', `/2/tweets/${replied.body.data.id}`);
+    check('delete answers {data:{deleted:true}}', deleted.status === 200 && deleted.body?.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?.type === 'about:blank'
+        && noAuth.body?.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?.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?.errors?.[0]?.resource_type === 'tweet'
+        && orphanReply.body?.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?.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?.data ?? {}).sort().join(',') === 'edit_history_tweet_ids,id,text'
+        && looked.body.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?.data?.author_id === '1000'
+        && projected.body.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?.data === undefined
+        && ghost.body?.errors?.[0]?.resource_type === 'tweet'
+        && ghost.body.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?.data?.length === 1
+        && bulk.body.data[0].id === createdBody.data.id
+        && bulk.body?.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?.data ?? []).some((row) => 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?.data ?? []).some((row) => row.id === createdBody.data.id)
+        && searchUnsupported.status === 400
+        && searchUnsupported.body?.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?.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?.errors?.[0]?.parameters?.text?.[0] === '281');
+    return { ok: failures.length === 0, checksRun: 18, failures };
+}

package/dist/src/x-connector.d.ts

@@ -0,0 +1,125 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { XBudget, type XBudgetOptions } from './x-budget.js';
+/** The modelled tweet.fields a pull requests — every field the twin's post rows can hold. */
+export declare const PULL_TWEET_FIELDS: readonly ["author_id", "created_at", "conversation_id", "in_reply_to_user_id", "referenced_tweets"];
+export type XExecute = (method: 'GET' | 'POST' | 'DELETE', path: string, init?: {
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<Record<string, any>>;
+export type LiveXOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: XBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: XBudgetOptions;
+};
+/**
+ * A live executor against the real X API, holding the operator's OWN user access token.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live X request, and therefore the one place the rate
+ * budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the request goes
+ * out (`checkBudget`, which THROWS instead of returning when the ceiling or a cooldown says stop)
+ * and the response is fed back (`recordCall`) so a 429 / `Retry-After` becomes a PERSISTED
+ * cooldown that makes every later call fail fast WITHOUT touching X. There is deliberately no
+ * option to disable the guard and no value of `budget` that yields an unguarded client
+ * (`assertBudgetGuardIntact`). This matters more here than on a read-only vendor: an unguarded
+ * loop at this vendor does not waste quota, it POSTS IN PUBLIC.
+ */
+export declare function liveXExecute(accessToken: string, opts?: LiveXOptions): XExecute;
+/** Map one real timeline post → the twin's `post` SyncResource. Nothing invented: a field the
+ *  response omits records NOTHING rather than a placeholder, so a partial reply can never fold a
+ *  null over a previously observed value. */
+export declare function mapTimelinePost(row: Record<string, any>): SyncResource;
+/** PULL the org's mentions timeline into the twin's observed log (idempotent). */
+export declare function pullXMentions(execute: XExecute, userId: string, root?: string, occurredAt?: string): Promise<number>;
+/** PULL the org's OWN posted timeline into the twin's observed log (idempotent). */
+export declare function pullXOwnTimeline(execute: XExecute, userId: string, root?: string, occurredAt?: string): Promise<number>;
+/**
+ * D7 consumer-facing pull entry point: pull everything readable from the real X posting surface
+ * and fold it into the twin in ONE shadow-diffed `syncPull`, returning the standard
+ * `{ observed, deltasAppended }`. Idempotent — a re-pull of identical state appends nothing.
+ */
+export declare function syncXFromReal(execute: XExecute, opts: {
+    userId: string;
+    root?: string;
+    occurredAt?: string;
+    includeOwnTimeline?: boolean;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * The request ONE pending twin action becomes at the real vendor. A pure shape builder — it
+ * issues nothing, so it can be asserted directly. The reply's discriminator travels here exactly
+ * as the twin read it: `reply.in_reply_to_tweet_id`, the same field, in the same place.
+ */
+export declare function xRequestForAction(action: {
+    operation?: string;
+    subject?: {
+        type: string;
+        id: string;
+    };
+    fields?: Record<string, any>;
+}): {
+    method: 'POST' | 'DELETE';
+    path: string;
+    body?: string;
+} | undefined;
+/**
+ * PUSH one pending action to the real vendor and confirm it with what the vendor answered.
+ *
+ * A create/reply is confirmed under the REAL id X minted, not the twin's locally minted one:
+ * after a push the public post has a public id, and a projection still claiming the local id
+ * would make every later delete address a post that does not exist. The local subject is
+ * confirmed as superseded in the same call.
+ */
+export declare function pushXAction(execute: XExecute, action: {
+    id: string;
+    operation?: string;
+    subject?: {
+        type: string;
+        id: string;
+    };
+    fields?: Record<string, any>;
+}, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    pushed: boolean;
+    realId?: string;
+    reason?: string;
+}>;
+/** Push every pending action this connector knows how to push. */
+export declare function pushPendingXActions(execute: XExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    pushed: number;
+    unpushable: number;
+}>;
+/**
+ * The perform adapter (runtime contract R18): what a World's deploy calls for each landed X entry
+ * on a twin whose root is the platform. A post, reply, quote or delete crosses through the host's
+ * executor, which adds the sealed credential; the kernel records the landing from the returned id.
+ * Anything else (a seeded account or token) is the twin's own record and crosses nothing. A
+ * reply's or quote's parent authored against a local id crosses against the id X minted for it.
+ */
+/**
+ * The kernel executor, charged to this pack's XBudget: the check RESERVES before the call and
+ * throws (XBudgetError) instead of calling when the ceiling, the burst bound or a cooldown says
+ * stop; the response settles the reservation and arms a cooldown on 429 / Retry-After.
+ */
+export declare function budgetedXExecute(execute: RemoteExecute, budget?: XBudget): RemoteExecute;
+export declare function performXAction(kernelExecute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;
+/** How long, in total, a perform waits on X's video processing before it fails the entry
+ *  retryably — the bound on a request at an `auto` head (see the header). */
+export declare const MAX_PROCESSING_WAIT_MS = 120000;
+/** At most this many STATUS reads per video, whatever `check_after_secs` says. */
+export declare const MAX_PROCESSING_POLLS = 30;
+/** The vendor has the video but has not finished processing it inside the bound: retry later. */
+export declare class XVideoStillProcessingError extends Error {
+    readonly mediaId: string;
+    readonly retryable = true;
+    constructor(mediaId: string, waitedMs: number, polls: number);
+}