@volter/twin-standard 1.0.29 → 1.0.31

package/dist/src/clients/sentry.js

@@ -0,0 +1,167 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Official SDKs at the demanded applications' pinned versions. The native HTTP module
+// takes the harness agent, preserving the SDK's DSN URL, compression, queue and wire.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { request as httpsRequest } from 'node:https';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+// The pins live in ../../client-sdks with their own lockfile, installed here on first use: some carry advisories with no
+// fix in the line an application pins, so the repository's install (and a release, .github/release-scan.mjs) never does.
+const SDKS = new URL('../../client-sdks/', import.meta.url);
+async function sdkOf(name) {
+    if (!existsSync(new URL('node_modules/', SDKS))) {
+        const install = spawnSync('bun', ['install', '--frozen-lockfile', '--ignore-scripts'], { cwd: SDKS, stdio: 'inherit' });
+        if (install.status !== 0)
+            throw new Error('client-sdks: bun install --frozen-lockfile failed');
+    }
+    return await import(__rewriteRelativeImportExtension(pathToFileURL(createRequire(new URL('package.json', SDKS)).resolve(name)).href));
+}
+const pins = [
+    ['rallly', '@sentry/node', '10.38.0'],
+    ['twenty', 'sentry-node-twenty', '10.73.0'],
+    ['postiz', 'sentry-node-postiz', '10.56.0'],
+    ['cal-api', 'sentry-node-cal', '9.46.0'],
+    ['cal-web', 'sentry-node-cal-web', '10.33.0'],
+];
+async function token(c) {
+    const answer = await c.fetch('https://' + c.host + '/_twin/auth-tokens', { method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ organization: c.env.SENTRY_ORG, name: 'SDK read-back', kind: 'personal', scopes: ['org:read', 'project:read', 'event:read'] }) });
+    if (!answer.ok)
+        throw new Error('read-back token: ' + answer.status);
+    return (await answer.json()).token;
+}
+async function read(c, id, auth) {
+    const answer = await c.fetch(`https://${c.host}/api/0/projects/${c.env.SENTRY_ORG}/${c.env.SENTRY_PROJECT}/events/${id}/`, { headers: { authorization: 'Bearer ' + auth } });
+    if (!answer.ok)
+        throw new Error('event read-back: ' + answer.status);
+    return await answer.json();
+}
+export const cases = pins.map(([application, name, version]) => ({
+    id: application + '-native-exception-flush-compression',
+    asks: 'captureException prepares its event ID, stack and scope; flush drains the native compressed envelope and its event reads back',
+    source: `https://unpkg.com/@sentry/core@${version}/build/esm/client.js "transport.flush(timeout)"`,
+    async run(c) {
+        const sdk = await sdkOf(name);
+        const requests = [];
+        const client = new sdk.NodeClient({ dsn: c.env.SENTRY_DSN, integrations: [], stackParser: sdk.defaultStackParser,
+            release: 'sdk-' + application, environment: 'sdk', transport: (options) => sdk.makeNodeTransport({ ...options,
+                httpModule: { request(options, callback) { requests.push({ url: String(options.path), encoding: options.headers?.['Content-Encoding'] ?? options.headers?.['content-encoding'] }); return httpsRequest({ ...options, agent: c.agent }, callback); } },
+            }) });
+        const scope = new sdk.Scope();
+        scope.setUser({ id: 'sdk-member' });
+        scope.setTag('application', application);
+        scope.setExtra('large-context', 'x'.repeat(64 * 1024));
+        const id = client.captureException(new Error('SDK ' + application + ' exception'), undefined, scope);
+        const drained = await client.flush(10_000);
+        const event = await read(c, id, await token(c));
+        await client.close(10_000);
+        const failures = [];
+        if (!drained || requests.length !== 1 || !requests[0].url.includes('/envelope/'))
+            failures.push('flush did not drain exactly one exception envelope');
+        if (requests[0]?.encoding !== 'gzip')
+            failures.push('large Node envelope was not compressed');
+        if (event.eventID !== id || event.user?.id !== 'sdk-member' || event.context?.['large-context']?.length !== 64 * 1024)
+            failures.push('event ID or scope did not survive the native transport');
+        if (!event.entries?.some((e) => e.type === 'exception' && e.data.values[0]?.stacktrace?.frames?.length))
+            failures.push('the SDK stack was lost');
+        return failures;
+    },
+}));
+for (const [name, version] of [['@sentry/browser', '10.38.0'], ['sentry-browser-twenty', '10.59.0'], ['sentry-browser-postiz', '10.56.0']])
+    cases.push({
+        id: 'browser-' + version + '-dsn-query-auth-and-session-envelope',
+        asks: 'the browser fetch transport uses DSN query authentication and flushes event and session envelopes',
+        source: `https://unpkg.com/@sentry/core@${version}/build/esm/api.js "sentry_key: publicKey"`,
+        async run(c) {
+            const sdk = await sdkOf(name);
+            const { makeSession } = await sdkOf('@sentry/core');
+            const sent = [];
+            const forward = (async (url, init) => { const request = new Request(url, init); sent.push(request.clone()); return c.fetch(request); });
+            const client = new sdk.BrowserClient({ dsn: c.env.SENTRY_DSN, integrations: [], stackParser: sdk.defaultStackParser,
+                transport: (options) => sdk.makeFetchTransport(options, forward) });
+            const id = client.captureEvent({ message: 'browser SDK case', level: 'error', platform: 'javascript' });
+            client.captureSession(makeSession({ release: 'sdk-browser', environment: 'sdk' }));
+            const drained = await client.flush(10_000);
+            const event = await read(c, id, await token(c));
+            await client.close(10_000);
+            return drained && sent.length === 2 && sent.every((r) => new URL(r.url).searchParams.has('sentry_key')) && event.message === 'browser SDK case' ? [] : ['browser queue, DSN query authentication or event/session envelopes failed'];
+        },
+    });
+cases.push({
+    id: 'twenty-cron-check-in-options-and-id',
+    asks: 'captureCheckIn creates an ID for in_progress and reuses it for ok with the monitor schedule and configured margins',
+    source: 'https://unpkg.com/@sentry/core@10.73.0/build/esm/server-runtime-client.js "checkin_margin: monitorConfig.checkinMargin"',
+    async run(c) {
+        const sdk = await sdkOf('sentry-node-twenty');
+        const sent = [];
+        const client = new sdk.NodeClient({ dsn: c.env.SENTRY_DSN, integrations: [], stackParser: sdk.defaultStackParser,
+            transport: (options) => sdk.createTransport(options, async (request) => {
+                sent.push(typeof request.body === 'string' ? request.body : new TextDecoder().decode(request.body));
+                const answer = await c.fetch(options.url, { method: 'POST', body: request.body });
+                return { statusCode: answer.status, headers: {} };
+            }) });
+        let id = '';
+        sdk.withScope((scope) => { scope.setClient(client); id = sdk.captureCheckIn({ monitorSlug: 'sdk-cleanup', status: 'in_progress' }, { schedule: { type: 'crontab', value: '0 3 * * *' }, checkinMargin: 1, maxRuntime: 5 }); sdk.captureCheckIn({ monitorSlug: 'sdk-cleanup', status: 'ok', checkInId: id }); });
+        const drained = await client.flush(10_000);
+        await client.close(10_000);
+        const payloads = sent.map((s) => JSON.parse(s.split('\n')[2]));
+        return drained && payloads.length === 2 && payloads[0].check_in_id === id && payloads[1].check_in_id === id && payloads[0].monitor_config.checkin_margin === 1 && payloads[0].monitor_config.max_runtime === 5 && !('duration' in payloads[1]) ? [] : ['check-in ID or monitor options changed'];
+    },
+});
+cases.push({
+    id: 'transport-rate-limit-drop-and-no-retry',
+    asks: 'core transport drains its queue, drops a rate-limited category and does not retry a 503',
+    source: 'https://unpkg.com/@sentry/core@10.38.0/build/esm/transports/base.js "ratelimit_backoff"',
+    async run(c) {
+        const sdk = await sdkOf('@sentry/core');
+        const ds = new URL(c.env.SENTRY_DSN);
+        const url = `https://${ds.host}/api${ds.pathname}/envelope/?sentry_key=${ds.username}&sentry_version=7`;
+        let attempts = 0;
+        const dropped = [];
+        const transport = sdk.createTransport({ recordDroppedEvent: (reason) => { dropped.push(reason); } }, async (request) => {
+            attempts++;
+            if (attempts === 1)
+                return { statusCode: 503, headers: {} };
+            const response = await c.fetch(url, { method: 'POST', body: request.body });
+            return { statusCode: response.status, headers: { 'x-sentry-rate-limits': '60:error:organization' } };
+        });
+        const envelope = (id) => sdk.createEnvelope({ event_id: id }, [[{ type: 'event' }, { event_id: id, message: 'transport SDK case', platform: 'javascript' }]]);
+        await transport.send(envelope('00000000000000000000000000000001'));
+        await transport.send(envelope('00000000000000000000000000000002'));
+        await transport.send(envelope('00000000000000000000000000000003'));
+        const drained = await transport.flush(10_000);
+        return drained && attempts === 2 && dropped.includes('ratelimit_backoff') ? [] : ['transport retried 503, failed to drain, or sent a rate-limited event'];
+    },
+});
+cases.push({
+    id: 'postiz-feedback-attribution',
+    asks: 'captureFeedback preserves the widget message, explicit name/email, associated event and scoped user',
+    source: 'https://unpkg.com/@sentry/core@10.56.0/build/esm/feedback.js "associated_event_id: associatedEventId"',
+    async run(c) {
+        const sdk = await sdkOf('sentry-browser-postiz');
+        const client = new sdk.BrowserClient({ dsn: c.env.SENTRY_DSN, integrations: [], stackParser: sdk.defaultStackParser,
+            transport: (options) => sdk.createTransport(options, async (request) => {
+                const answer = await c.fetch(options.url, { method: 'POST', body: request.body });
+                return { statusCode: answer.status, headers: {} };
+            }) });
+        let id = '';
+        sdk.withScope((scope) => {
+            scope.setClient(client);
+            scope.setUser({ id: 'feedback-author' });
+            id = sdk.captureFeedback({ message: 'The scheduling button is hard to find', name: 'Priya', email: 'priya@harbourline.test', associatedEventId: '00000000000000000000000000000002' }, {}, scope);
+        });
+        const drained = await client.flush(10_000);
+        const event = await read(c, id, await token(c));
+        await client.close(10_000);
+        const feedback = event.contexts?.feedback;
+        return drained && event.type === 'feedback' && event.user?.id === 'feedback-author' && feedback?.name === 'Priya' && feedback?.contact_email === 'priya@harbourline.test' && feedback?.associated_event_id === '00000000000000000000000000000002' ? [] : ['feedback attribution or associated event was lost'];
+    },
+});

package/dist/src/clients/slack.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/slack.js

@@ -0,0 +1,107 @@
+const MESSAGE = 'https://docs.slack.dev/reference/events/message.channels';
+const UPLOADS = 'https://docs.slack.dev/messaging/working-with-files';
+/** A message event's fields as Slack documents them (its example payload, and the fields a message carries). */
+const MESSAGE_FIELDS = new Set(['type', 'subtype', 'channel', 'user', 'text', 'ts', 'event_ts', 'channel_type', 'thread_ts', 'parent_user_id', 'blocks', 'team', 'client_msg_id', 'bot_id', 'app_id', 'bot_profile', 'attachments', 'files', 'edited', 'username', 'icons', 'upload', 'display_as_bot']);
+/** A workspace, a channel, and an app with Socket Mode subscribed to the channel's messages, installed by the workspace's
+ *  owner through Slack's own pages and API, as a team sets one up. */
+async function install(c) {
+    const person = 'xoxp-UMAYA';
+    const call = async (url, body, token) => c.fetch(url, { method: 'POST', redirect: 'manual', headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) }, body: JSON.stringify(body) });
+    const json = async (r) => (await r.json());
+    await call('https://slack.com/get-started', { email: 'maya@kiln.studio', name: 'Maya Okafor' }, person);
+    const channel = (await json(await call('https://slack.com/api/conversations.create', { name: 'studio' }, person))).channel?.id;
+    const config = /access token is (xoxe\.xoxp-[A-Za-z0-9-]+)/.exec(await (await call('https://api.slack.com/apps', { team: 'T-twin' }, person)).text())?.[1];
+    if (!channel || !config)
+        throw new Error(`the workspace or its app configuration token was not made (channel ${channel}, token ${config})`);
+    const app = await json(await call('https://slack.com/api/apps.manifest.create', { manifest: {
+            display_information: { name: 'Conformance Bot' },
+            features: { bot_user: { display_name: 'conformance_bot' } },
+            oauth_config: { redirect_urls: ['https://bot.example.com/slack/oauth'], scopes: { bot: ['chat:write', 'channels:history', 'files:write'] } },
+            settings: { socket_mode_enabled: true, event_subscriptions: { bot_events: ['message.channels'] } },
+        } }, config));
+    if (!app.ok)
+        throw new Error(`apps.manifest.create: ${JSON.stringify(app).slice(0, 160)}`);
+    const allowed = await call('https://slack.com/oauth/v2/authorize', { client_id: app.credentials.client_id, scope: 'chat:write,channels:history,files:write', redirect_uri: 'https://bot.example.com/slack/oauth', state: 'conform', answer: 'allow' }, person);
+    const code = new URL(allowed.headers.get('location') ?? 'http://x/').searchParams.get('code');
+    if (!code)
+        throw new Error(`the install was not allowed (${allowed.status})`);
+    const access = await json(await call('https://slack.com/api/oauth.v2.access', { client_id: app.credentials.client_id, client_secret: app.credentials.client_secret, code, redirect_uri: 'https://bot.example.com/slack/oauth' }));
+    const appToken = /The token is (xapp-[A-Za-z0-9-]+)/.exec(await (await call(`https://api.slack.com/apps/${app.app_id}/app-level-tokens`, { name: 'conformance', scopes: 'connections:write' }, person)).text())?.[1];
+    if (!access.ok || !appToken)
+        throw new Error(`the bot or app-level token was not issued (${JSON.stringify(access).slice(0, 120)})`);
+    await call('https://slack.com/api/conversations.invite', { channel, users: access.bot_user_id }, person);
+    return { channel, botUser: String(access.bot_user_id), botToken: String(access.access_token), appToken, person };
+}
+export const cases = [
+    {
+        id: 'socket-mode-message',
+        asks: "an app's Socket Mode client hears a person's message in its bot's channel as Slack documents the event, with nothing else in it",
+        source: `${MESSAGE} "The semantics for this event"`,
+        async run(c) {
+            const installed = await install(c);
+            const { SocketModeClient } = await import('@slack/socket-mode');
+            const { WebClient, LogLevel } = await import('@slack/web-api');
+            const socket = new SocketModeClient({ appToken: installed.appToken, logLevel: LogLevel.ERROR, clientOptions: { agent: c.agent } });
+            const heard = new Promise((resolve) => {
+                const timer = setTimeout(() => resolve('no message event in 10 s'), 10_000);
+                socket.on('message', async ({ event, ack }) => { await ack(); clearTimeout(timer); resolve(event); });
+            });
+            const started = await socket.start().then(() => undefined, (e) => e.message);
+            if (started)
+                return [`the Socket Mode client did not connect: ${started}`];
+            const person = new WebClient(installed.person, { agent: c.agent, logLevel: LogLevel.ERROR });
+            await person.chat.postMessage({ channel: installed.channel, text: 'The client brief is in.' });
+            const event = await heard;
+            await socket.disconnect().catch(() => undefined);
+            if (typeof event === 'string')
+                return [event];
+            const out = [];
+            for (const k of ['type', 'channel', 'user', 'text', 'ts', 'event_ts', 'channel_type'])
+                if (event[k] === undefined)
+                    out.push(`the event carries no ${k}, which Slack's payload has`);
+            for (const k of Object.keys(event))
+                if (!MESSAGE_FIELDS.has(k))
+                    out.push(`the event carries ${k}, which no Slack message event has`);
+            if (event.text !== 'The client brief is in.')
+                out.push(`the event's text is ${JSON.stringify(event.text)}`);
+            return out;
+        },
+    },
+    {
+        id: 'files-upload-v2',
+        asks: "an app's files.uploadV2 sends a file's bytes to the upload URL Slack answers and completes the upload into a thread, where the file reads back with its size",
+        source: `${UPLOADS} "Post the contents of your file to the URL returned by the files.getUploadURLExternal API method"`,
+        async run(c) {
+            const installed = await install(c);
+            const { WebClient, LogLevel } = await import('@slack/web-api');
+            const bot = new WebClient(installed.botToken, { agent: c.agent, logLevel: LogLevel.ERROR });
+            const root = await bot.chat.postMessage({ channel: installed.channel, text: 'Render finished' });
+            if (!root.ts)
+                return [`the thread's first message was not posted: ${JSON.stringify(root).slice(0, 160)}`];
+            const bytes = Buffer.from('frame,seconds\n1,0.42\n2,0.40\n');
+            let uploaded;
+            try {
+                // as the Chat SDK's Slack adapter calls it: the files in file_uploads, the thread's channel_id and thread_ts
+                uploaded = await bot.files.uploadV2({ channel_id: installed.channel, thread_ts: root.ts, file_uploads: [{ file: bytes, filename: 'timings.csv' }] });
+            }
+            catch (e) {
+                return [`files.uploadV2 failed: ${e.message}`];
+            }
+            const id = uploaded.files?.[0]?.files?.[0]?.id;
+            if (!uploaded.ok || !id)
+                return [`files.uploadV2 answered no file: ${JSON.stringify(uploaded).slice(0, 200)}`];
+            const replies = await bot.conversations.replies({ channel: installed.channel, ts: root.ts });
+            const shared = (replies.messages ?? []).flatMap((m) => (m.files ?? []).map((f) => ({ f, thread: m.thread_ts }))).find((x) => x.f.id === id);
+            const out = [];
+            if (!shared)
+                out.push(`the thread holds no message carrying file ${id}`);
+            else {
+                if (shared.thread !== root.ts)
+                    out.push(`the file's message is in thread ${String(shared.thread)}, not ${root.ts}`);
+                if (shared.f.size !== bytes.length)
+                    out.push(`the file's size is ${String(shared.f.size)}, not the ${bytes.length} bytes sent`);
+            }
+            return out;
+        },
+    },
+];

package/dist/src/clients/stripe.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/stripe.js

@@ -0,0 +1,161 @@
+// Stripe's own client (stripe-node), driving the stripe pack as its applications do (Cal.com, Dub, Postiz, Rallly and
+// Twenty call it): an endpoint registered through the API and the event Stripe sends it verified by constructEvent, as an
+// application's webhook handler verifies it; a customer list read page by page by the client's auto-pagination; a retry
+// sent with its idempotency key; the error a missing object raises; and the customer portal a billing page opens.
+import { createServer } from 'node:http';
+const SIGNATURE = 'https://docs.stripe.com/webhooks/signature';
+const EVENT = 'https://docs.stripe.com/api/events/object';
+const PAGINATION = 'https://docs.stripe.com/api/pagination/auto';
+const IDEMPOTENCY = 'https://docs.stripe.com/api/idempotent_requests';
+const ERRORS = 'https://docs.stripe.com/api/errors/handling';
+const PORTAL = 'https://docs.stripe.com/api/customer_portal/sessions/object';
+const failed = (what) => (e) => new Error(`${what} failed: ${e.name}: ${e.message}`);
+async function stripe(c) {
+    const { default: Stripe } = await import('stripe');
+    return new Stripe(c.env.STRIPE_SECRET_KEY ?? '', { httpAgent: c.agent, maxNetworkRetries: 0, timeout: 10_000 });
+}
+export const cases = [
+    {
+        id: 'webhook-event-verified',
+        asks: "the event Stripe sends an endpoint is verified by its secret, and its data.object is the customer as the API answers it",
+        source: `${SIGNATURE} "use the Stripe-Signature header and call the constructEvent() function"; ${EVENT} "Object containing the API resource relevant to the event."`,
+        async run(c) {
+            // the application's endpoint: a server of this process, as an application's own
+            const received = [];
+            const receiver = createServer((req, res) => {
+                let body = '';
+                req.on('data', (d) => { body += d; });
+                req.on('end', () => { received.push({ body, signature: String(req.headers['stripe-signature'] ?? '') }); res.end('{}'); });
+            });
+            await new Promise((r) => receiver.listen(0, '127.0.0.1', () => r()));
+            const port = receiver.address().port;
+            try {
+                const client = await stripe(c);
+                const endpoint = await client.webhookEndpoints.create({ url: `http://127.0.0.1:${port}/stripe`, enabled_events: ['customer.created'] });
+                const customer = await client.customers.create({ email: 'ada@example.com', name: 'Ada Lovelace' });
+                for (let i = 0; i < 50 && !received.length; i++)
+                    await new Promise((r) => setTimeout(r, 100));
+                const delivery = received[0];
+                if (!delivery)
+                    return ['no event reached the endpoint in 5 s'];
+                let event;
+                try {
+                    event = client.webhooks.constructEvent(delivery.body, delivery.signature, String(endpoint.secret));
+                }
+                catch (e) {
+                    return [`constructEvent refused the delivery: ${e.message}`];
+                }
+                const out = [];
+                if (event.type !== 'customer.created')
+                    out.push(`the event is ${event.type}`);
+                const object = event.data.object;
+                if (object.id !== customer.id)
+                    out.push(`data.object is ${String(object.id)}, not the customer made (${customer.id})`);
+                const answered = await client.customers.retrieve(customer.id);
+                for (const k of Object.keys(object))
+                    if (!(k in answered))
+                        out.push(`data.object carries ${k}, which the API's customer does not`);
+                return out;
+            }
+            finally {
+                receiver.close();
+            }
+        },
+    },
+    {
+        id: 'customers-auto-paginated',
+        asks: 'a list read with the client\'s auto-pagination, two to a page, holds every customer of the email, newest first, across its pages',
+        source: `${PAGINATION} "This feature allows you to easily iterate through large lists of resources without having to manually perform the requests to fetch subsequent pages."`,
+        async run(c) {
+            try {
+                const client = await stripe(c);
+                const made = [];
+                for (const name of ['Ada Lovelace', 'Grace Hopper', 'Katherine Johnson']) {
+                    made.push((await client.customers.create({ email: 'team@analytical.example', name }).catch((e) => { throw failed('customers.create')(e); })).id);
+                }
+                const listed = await client.customers.list({ email: 'team@analytical.example', limit: 2 }).autoPagingToArray({ limit: 10 }).catch((e) => { throw failed('customers.list auto-pagination')(e); });
+                const ids = listed.map((x) => x.id);
+                const expected = [...made].reverse();
+                return ids.join(',') === expected.join(',') ? [] : [`auto-pagination read ${ids.join(', ') || 'nothing'}, not the three customers newest first (${expected.join(', ')})`];
+            }
+            catch (e) {
+                return [e.message];
+            }
+        },
+    },
+    {
+        id: 'idempotent-retry',
+        asks: 'a create retried with its idempotency key answers the first create\'s customer, and the key sent with other parameters is refused',
+        source: `${IDEMPOTENCY} "Subsequent requests with the same key return the same result"; ${IDEMPOTENCY} "The idempotency layer compares incoming parameters to those of the original request and errors if they’re not the same to prevent accidental misuse."`,
+        async run(c) {
+            try {
+                const client = await stripe(c);
+                const key = 'client-case-signup-ada';
+                const first = await client.customers.create({ email: 'ada@example.com', name: 'Ada Lovelace' }, { idempotencyKey: key }).catch((e) => { throw failed('customers.create')(e); });
+                const retried = await client.customers.create({ email: 'ada@example.com', name: 'Ada Lovelace' }, { idempotencyKey: key }).catch((e) => { throw failed('customers.create, retried')(e); });
+                const out = [];
+                if (retried.id !== first.id)
+                    out.push(`the retry made ${retried.id}, not the first create's ${first.id}`);
+                const misuse = await client.customers.create({ email: 'grace@example.com', name: 'Grace Hopper' }, { idempotencyKey: key }).then(() => undefined, (e) => e);
+                if (!misuse)
+                    out.push('the key sent with other parameters made a customer');
+                else if (misuse.type !== 'StripeIdempotencyError')
+                    out.push(`the key sent with other parameters raised ${String(misuse.type)}, not StripeIdempotencyError`);
+                return out;
+            }
+            catch (e) {
+                return [e.message];
+            }
+        },
+    },
+    {
+        id: 'missing-object-error',
+        asks: 'retrieving a customer that does not exist raises the client\'s invalid-request error, 404, code resource_missing',
+        source: `${ERRORS} "Our client libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability."`,
+        async run(c) {
+            try {
+                const client = await stripe(c);
+                const raised = await client.customers.retrieve('cus_never_made').then(() => undefined, (e) => e);
+                if (!raised)
+                    return ['retrieving a customer that does not exist answered one'];
+                const out = [];
+                if (raised.type !== 'StripeInvalidRequestError')
+                    out.push(`it raised ${String(raised.type)}, not StripeInvalidRequestError`);
+                if (raised.statusCode !== 404)
+                    out.push(`its status is ${String(raised.statusCode)}, not 404`);
+                if (raised.code !== 'resource_missing')
+                    out.push(`its code is ${String(raised.code)}, not resource_missing`);
+                return out;
+            }
+            catch (e) {
+                return [e.message];
+            }
+        },
+    },
+    {
+        id: 'portal-session-opens',
+        asks: 'a portal session made for a customer answers its return_url and a url on billing.stripe.com, and that url opens the customer portal',
+        source: `${PORTAL} "The short-lived URL of the session that gives customers access to the customer portal."`,
+        async run(c) {
+            try {
+                const client = await stripe(c);
+                const customer = await client.customers.create({ email: 'billing@analytical.example', name: 'Analytical Engines' }).catch((e) => { throw failed('customers.create')(e); });
+                const session = await client.billingPortal.sessions.create({ customer: customer.id, return_url: 'https://app.analytical.example/billing' }).catch((e) => { throw failed('billingPortal.sessions.create')(e); });
+                const out = [];
+                if (session.return_url !== 'https://app.analytical.example/billing')
+                    out.push(`the session's return_url is ${String(session.return_url)}`);
+                if (!session.url.startsWith('https://billing.stripe.com/')) {
+                    out.push(`the session's url is ${session.url}, not on billing.stripe.com`);
+                    return out;
+                }
+                const page = await c.fetch(session.url);
+                if (page.status !== 200)
+                    out.push(`the portal page answered ${page.status}`);
+                return out;
+            }
+            catch (e) {
+                return [e.message];
+            }
+        },
+    },
+];

package/dist/src/clients/tinybird.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/tinybird.js

@@ -0,0 +1,71 @@
+const SDK = 'https://unpkg.com/@tinybirdco/sdk@0.0.84/src/api/api.ts';
+async function client(c, fetch = c.fetch) {
+    const { createTinybirdApi } = await import('@tinybirdco/sdk/api');
+    return createTinybirdApi({ baseUrl: `https://${c.host}`, token: c.env.TINYBIRD_API_KEY ?? c.env.TINYBIRD_TOKEN ?? '', fetch });
+}
+export const cases = [
+    {
+        id: 'request-token-override-and-typed-error',
+        asks: 'a request token override is used instead of the Workspace token, and its refusal retains the status and JSON error in TinybirdApiError',
+        source: `${SDK} "Error thrown by TinybirdApi when a response is not OK"`,
+        async run(c) {
+            const { TinybirdApiError } = await import('@tinybirdco/sdk/api');
+            const api = await client(c);
+            try {
+                await api.ingest('client_case_events', { label: 'refused' }, { token: 'throwaway-invalid-token' });
+                return ['the invalid request token was accepted'];
+            }
+            catch (error) {
+                if (!(error instanceof TinybirdApiError))
+                    return [`the refusal is not TinybirdApiError: ${String(error)}`];
+                const failures = [];
+                if (error.statusCode !== 403)
+                    failures.push(`the invalid token answered ${error.statusCode}, not 403`);
+                if (!error.response?.error || error.message !== error.response.error)
+                    failures.push('the vendor error message did not survive SDK decoding');
+                if (!error.responseBody || JSON.stringify(JSON.parse(error.responseBody)) !== JSON.stringify(error.response))
+                    failures.push('the parsed error does not retain the raw vendor response');
+                return failures;
+            }
+        },
+    },
+    {
+        id: 'date-rejection-and-ndjson-batch',
+        asks: 'Date objects are refused locally, then two valid event records are serialized as NDJSON without losing quoted text or line breaks',
+        source: `${SDK} "Date values are not supported in ingest payloads."`,
+        async run(c) {
+            let calls = 0;
+            const routed = ((input, init) => { calls++; return c.fetch(input, init); });
+            const api = await client(c, routed);
+            try {
+                await api.ingest('client_case_events', { timestamp: new Date('2024-01-15T10:30:00Z') });
+                return ['a Date object was accepted for ingestion'];
+            }
+            catch (error) {
+                if (!(error instanceof Error) || !error.message.includes('Date values are not supported in ingest payloads.'))
+                    return [`the Date refusal was ${String(error)}`];
+                if (calls !== 0)
+                    return ['the SDK sent a request before refusing the Date object'];
+            }
+            await api.requestJson('/v0/datasources', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ name: 'client_case_events', schema: 'label String, timestamp DateTime' }).toString() });
+            const rows = [{ label: 'a "quoted" value', timestamp: '2024-01-15 10:30:00' }, { label: 'two\nlines', timestamp: '2024-01-15 10:31:00' }];
+            const ingested = await api.ingestBatch('client_case_events', rows, { wait: true });
+            const result = await api.sql('SELECT label, timestamp FROM client_case_events ORDER BY timestamp');
+            return ingested.successful_rows === 2 && ingested.quarantined_rows === 0 && JSON.stringify(result.data) === JSON.stringify(rows)
+                ? [] : [`NDJSON batch/read-back differs: ${JSON.stringify({ ingested, rows: result.data })}`];
+        },
+    },
+    {
+        id: 'json-query-parameter-serialization',
+        asks: 'an object query parameter becomes JSON and the Endpoint uses its value rather than the object string representation',
+        source: `${SDK} "Plain objects (e.g. p.json() params) become JSON strings; Dates are rejected;"`,
+        async run(c) {
+            const api = await client(c);
+            await api.requestJson('/v0/datasources', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ name: 'client_json_rows', schema: 'name String' }).toString() });
+            await api.ingestBatch('client_json_rows', [{ name: 'selected' }, { name: 'excluded' }], { wait: true });
+            await api.requestJson('/v0/pipes', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name: 'client_json_filter', nodes: [{ name: 'endpoint', type: 'endpoint', sql: "%\nSELECT name FROM client_json_rows WHERE name = {{JSON(filters, '{\"name\":\"selected\"}').get('name')}}" }] }) });
+            const result = await api.query('client_json_filter', { filters: { name: 'excluded' } });
+            return JSON.stringify(result.data) === JSON.stringify([{ name: 'excluded' }]) ? [] : [`the JSON parameter selected ${JSON.stringify(result.data)}`];
+        },
+    },
+];

package/dist/src/clients/tunnel.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/tunnel.js

@@ -0,0 +1,99 @@
+// The relay's unmodified client forwards a local application's HTTP responses through the control socket.
+// Expectations are the pinned protocol and relay reference, never the pack author's scripted frames.
+import { Agent } from 'node:https';
+import { createServer } from 'node:http';
+export const cases = [{
+        id: 'local-http-relay',
+        asks: 'createTunnel preserves visitor method/body/public host and streams local responses, including HEAD, 204 and 304',
+        source: 'https://github.com/volter-ai/volter-tunnel/blob/c14b6e36722b20cbb3ee7245c7f555b5c12b376e/packages/core/src/protocol.ts "An inbound HTTP request to forward to the local server."',
+        async run(c) {
+            const failures = [];
+            const local = createServer(async (request, response) => {
+                const chunks = [];
+                for await (const chunk of request)
+                    chunks.push(Buffer.from(chunk));
+                const path = request.url ?? '';
+                if (path === '/empty') {
+                    response.writeHead(204);
+                    response.end();
+                    return;
+                }
+                if (path === '/cached') {
+                    response.writeHead(304);
+                    response.end();
+                    return;
+                }
+                if (request.method === 'HEAD') {
+                    response.writeHead(200, { 'x-local-head': 'present' });
+                    response.end();
+                    return;
+                }
+                response.writeHead(200, { 'content-type': 'application/json', 'x-frame-options': 'DENY', 'content-security-policy': "default-src 'self'; frame-ancestors 'none'" });
+                response.write(JSON.stringify({ method: request.method, path, host: request.headers['x-forwarded-host'], appHeader: request.headers['x-volter-app'], body: Buffer.concat(chunks).toString() }));
+                response.end();
+            });
+            await new Promise((resolve) => local.listen(0, '127.0.0.1', resolve));
+            // The SDK owns its HTTPS agent. Route that agent's TCP connection as a World's injector does,
+            // retaining its secure relay URL and Host; local-origin connections retain their ordinary agent.
+            const original = Agent.prototype.createConnection;
+            Agent.prototype.createConnection = function (options, callback) {
+                if ((options.hostname ?? options.host) === c.host)
+                    return c.connect();
+                return original.call(this, options, callback);
+            };
+            let tunnel;
+            try {
+                const { createTunnel } = await import('@volter/tunnel/client');
+                tunnel = await createTunnel({ host: `https://${c.host}`, port: local.address().port,
+                    tunnelId: 'conform-harness', secret: c.env.TUNNEL_SECRET, authRequired: false,
+                    logger: { info() { }, warn() { }, debug() { } }, });
+                if (tunnel.url !== 'https://conform-harness.voltertest.xyz')
+                    failures.push('registered URL differs from the requested tunnel');
+                const answer = await c.fetch(`${tunnel.url}/command?view=demo`, { method: 'POST',
+                    headers: { 'content-type': 'text/plain', 'x-volter-app': 'custom', origin: 'https://viewer.example' }, body: 'run demo' });
+                const body = await answer.json();
+                for (const [key, expected] of Object.entries({ method: 'POST', path: '/command?view=demo', host: 'conform-harness.voltertest.xyz', appHeader: 'custom', body: 'run demo' })) {
+                    if (body[key] !== expected)
+                        failures.push(`local request ${key}: ${JSON.stringify(body[key])}`);
+                }
+                // Node fetch injection rewrites the URL to the listener and carries the original vendor host.
+                const injected = await c.fetch('http://127.0.0.1/injected', { headers: {
+                        'x-volter-twin-original-host': 'conform-harness.voltertest.xyz', 'x-volter-app': 'injected',
+                    } });
+                if (injected.status !== 200)
+                    failures.push('World-injected visitor did not reach its registered tunnel');
+                else {
+                    const body = await injected.json();
+                    if (body.host !== 'conform-harness.voltertest.xyz' || body.path !== '/injected' || body.appHeader !== 'injected') {
+                        failures.push('World-injected visitor lost its public host or application headers');
+                    }
+                }
+                if (answer.headers.get('access-control-allow-origin') !== 'https://viewer.example')
+                    failures.push('CORS origin not reflected');
+                if (answer.headers.has('x-frame-options') || answer.headers.get('content-security-policy')?.includes('frame-ancestors'))
+                    failures.push('embedding restrictions not stripped');
+                if (answer.headers.get('cache-control') !== 'private, no-store, max-age=0')
+                    failures.push('dynamic response cache policy missing');
+                for (const [path, method, status] of [['/empty', 'GET', 204], ['/cached', 'GET', 304], ['/head', 'HEAD', 200]]) {
+                    const response = await c.fetch(`${tunnel.url}${path}`, { method });
+                    if (response.status !== status || (await response.text()) !== '')
+                        failures.push(`${method} ${path} is not bodyless ${status}`);
+                }
+                const preflight = await c.fetch(`${tunnel.url}/command`, { method: 'OPTIONS', headers: {
+                        origin: 'https://viewer.example', 'access-control-request-headers': 'X-Demo',
+                    } });
+                if (preflight.status !== 204 || preflight.headers.get('access-control-allow-headers') !== 'X-Demo')
+                    failures.push('preflight does not reflect requested headers');
+                const tooLarge = await c.fetch(`${tunnel.url}/upload`, { method: 'POST', body: 'x'.repeat(750_001) });
+                if (tooLarge.status !== 413)
+                    failures.push('oversized request was forwarded');
+            }
+            finally {
+                tunnel?.close();
+                Agent.prototype.createConnection = original;
+                local.closeAllConnections();
+                await new Promise((resolve) => local.close(() => resolve()));
+            }
+            return failures;
+        },
+    }];

package/dist/src/clients/upstash.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];