ts-server-lib 0.0.17

package/utils/TSRequest.js

@@ -0,0 +1,256 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSRequest = void 0;
+exports.request = request;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const querystring_1 = require("querystring");
+const fast_xml_parser_1 = require("fast-xml-parser");
+const abort_1 = require("./abort");
+class TSRequest {
+    static async form(url, options = {}, debug) {
+        options.headers = {
+            ...{ 'Accept': '*/*', 'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8' }, ...(options.headers || {})
+        };
+        options.acceptAll = debug;
+        options.bcb = JSON.parse;
+        if (options.body !== null && typeof options.body === 'object' && !Buffer.isBuffer(options.body)) {
+            options.body = (0, querystring_1.stringify)(options.body);
+        }
+        const start = new Date();
+        return new Promise((resolve, reject) => TSRequest.raw(url, options).then(response => {
+            if (debug) {
+                console.log(`TSRequest:[${Number(new Date()) - Number(start)} ms][${url}]`, JSON.stringify({ REQUEST: options, RESPONSE: response }, null, 2));
+            }
+            if (response) {
+                resolve(response);
+            }
+            else {
+                resolve(response);
+            }
+        }).catch(error => {
+            error.took = `TSRequest:[${Number(new Date()) - Number(start)} ms][${url}]`;
+            error.options = options;
+            reject(error);
+        }));
+    }
+    static async xml(url, options = {}, debug) {
+        const start = new Date();
+        options.headers = {
+            ...{ 'Accept': 'text/xml', 'Content-Type': 'text/xml; charset=UTF-8' }, ...(options.headers || {})
+        };
+        options.acceptAll = debug;
+        if (options.body !== null && typeof options.body === 'object' && !Buffer.isBuffer(options.body)) {
+            options.body = new fast_xml_parser_1.XMLBuilder({ ignoreAttributes: false, attributeNamePrefix: '', attributesGroupName: '$', textNodeName: '_' }).build(options.body);
+        }
+        if (options.body != null && options.body !== '') {
+            Buffer.byteLength(typeof options.body === 'string' ? options.body : String(options.body));
+        }
+        return new Promise((resolve, reject) => TSRequest.raw(url, options).then((response) => {
+            if (debug) {
+                console.log(`TSRequest:[${Number(new Date()) - Number(start)} ms][${url}]`, JSON.stringify({ REQUEST: options, RESPONSE: response }, null, 2));
+            }
+            try {
+                resolve(new fast_xml_parser_1.XMLParser({ ignoreAttributes: false, attributeNamePrefix: '', attributesGroupName: '$', textNodeName: '_', isArray: (_n, jPath, _l, isAttr) => !isAttr && String(jPath).includes('.') }).parse(String(response ?? '')));
+            }
+            catch (error) {
+                reject(error);
+            }
+        }).catch(error => {
+            error.took = `TSRequest:[${Number(new Date()) - Number(start)} ms][${url}]`;
+            error.options = options;
+            reject(error);
+        }));
+    }
+    static async json(url, options = {}, debug) {
+        options.headers = {
+            ...{ 'Accept': 'application/json', 'Content-Type': 'application/json; charset=UTF-8' }, ...(options.headers || {})
+        };
+        options.acceptAll = debug;
+        options.bcb = (response) => {
+            try {
+                return JSON.parse(response);
+            }
+            catch (e) {
+                console.error(e);
+                return response;
+            }
+        };
+        if (options.body !== null && typeof options.body === 'object' && !Buffer.isBuffer(options.body)) {
+            options.body = JSON.stringify(options.body);
+        }
+        const start = new Date();
+        return new Promise((resolve, reject) => TSRequest.raw(url, options).then(response => {
+            if (debug) {
+                console.log(`TSRequest:[${Number(new Date()) - Number(start)} ms][${url}]`, JSON.stringify({ REQUEST: options, RESPONSE: response }, null, 2));
+            }
+            if (response && response.data) {
+                resolve(response.data);
+            }
+            else {
+                resolve(response);
+            }
+        }).catch(error => {
+            error.took = `TSRequest:[${Number(new Date()) - Number(start)} ms][${url}]`;
+            error.options = options;
+            reject(error);
+        }));
+    }
+    static async raw(url, options = {}) {
+        const signal = options.signal;
+        if (signal?.aborted) {
+            return Promise.reject((0, abort_1.abortError)());
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let req;
+            let onAbort;
+            const cleanupAbort = () => {
+                if (signal && onAbort) {
+                    signal.removeEventListener('abort', onAbort);
+                }
+            };
+            const finish = (action, value, err) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanupAbort();
+                if (action === 'resolve') {
+                    resolve(value);
+                }
+                else {
+                    reject(err);
+                }
+            };
+            if (signal) {
+                onAbort = () => {
+                    const abortErr = (0, abort_1.abortError)();
+                    try {
+                        req?.destroy(abortErr);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    finish('reject', undefined, abortErr);
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+            const params = TSRequest.url(url);
+            const optsForRequest = { ...options };
+            delete optsForRequest.signal;
+            Object.assign(params, optsForRequest);
+            if (!params.method) {
+                params.method = 'get';
+            }
+            if (params.search) {
+                params.path = params.path + params.search;
+            }
+            if (params.qs) {
+                params.path = params.path + (params.path.indexOf('?') > -1 ? '&' : '?') + (0, querystring_1.stringify)(params.qs);
+            }
+            try {
+                req = (params.protocol === 'https:' ? https : http).request(params, res => {
+                    const statusCode = res.statusCode ?? 0;
+                    if (!params.acceptAll && (statusCode < 200 || statusCode >= 300)) {
+                        res.resume();
+                        finish('reject', undefined, TSRequest.error('response', statusCode, { statusMessage: res.statusMessage, headers: res.headers }));
+                        return;
+                    }
+                    const chunks = [];
+                    res.on('data', chunk => chunks.push(chunk));
+                    res.on('end', () => {
+                        try {
+                            const buffer = Buffer.concat(chunks).toString();
+                            const body = params.bcb
+                                ? { kind: 'success', status: statusCode, message: res.statusMessage, headers: res.headers, data: params.bcb(buffer) }
+                                : buffer;
+                            finish('resolve', body);
+                        }
+                        catch (e) {
+                            const msg = e instanceof Error ? e.message : String(e);
+                            finish('reject', undefined, TSRequest.error('parse', !params.acceptAll ? 109 : statusCode, { statusMessage: res.statusMessage, headers: res.headers, error: msg, body: chunks }));
+                        }
+                    });
+                });
+                req.on('error', e => {
+                    finish('reject', undefined, TSRequest.error('error', 545, e.message));
+                });
+                req.on('timeout', () => {
+                    const error = TSRequest.error('timeout', 563, 'Request destroyed');
+                    req?.destroy(error);
+                    finish('reject', undefined, error);
+                });
+                if (options.body) {
+                    req.write(options.body);
+                }
+                req.end();
+            }
+            catch (e) {
+                const err = e instanceof Error ? e : new Error(String(e));
+                finish('reject', undefined, err);
+            }
+        });
+    }
+    static error(kind, status, message) {
+        return new Error(JSON.stringify({ kind: kind, status: status, message: message }));
+    }
+    static url(url) {
+        const m = /^(https?:)\/\/(([^:/?#]*)(?::([0-9]+))?)([/]{0,1}[^?#]*)(\?[^#]*|)(#.*|)$/.exec(url);
+        return m ? {
+            href: url, protocol: m[1], host: m[2], hostname: m[3], port: m[4], path: m[5], pathname: m[5], search: m[6], hash: m[7]
+        } : {};
+    }
+}
+exports.TSRequest = TSRequest;
+function request(url, { body = undefined, qs = undefined, debug = undefined, ...options } = {}, kind = 'json') {
+    if (!options) {
+        options = {};
+    }
+    if (body) {
+        options.body = body;
+    }
+    else if (qs) {
+        options.qs = qs;
+        options.method = 'get';
+    }
+    options.rejectUnauthorized = false;
+    options.timeout = options.timeout || 18000;
+    return new Promise(resolve => TSRequest[kind](url, options, debug).catch((error) => {
+        console.error(error);
+        resolve({});
+    }).then(data => resolve(data)));
+}

package/utils/TSStub.d.ts

@@ -0,0 +1,159 @@
+/**
+ * TSStub — generic driver stub utility for all at-prefixed provider packages.
+ *
+ * Provides the shared scaffolding every stub needs:
+ *   - Latency injection (fixed, random range, or abortable timeout)
+ *   - Error injection (network error, timeout, rate-limit exceeded)
+ *   - Outcome simulation (success / failure / pending / processing)
+ *   - Retry-N-then-succeed counter
+ *   - Webhook signature validation
+ *   - In-memory store with deterministic ID generation
+ *   - Rate-limit capability declaration
+ *   - OAuth token / session simulation (atsocial)
+ *   - Exchange rate table lookup (atexchange)
+ *   - Capability matrix helper (atsocial)
+ *   - Health status simulation (atkyc, others)
+ *   - Config field extractor (normalise simulate* + latency from raw config)
+ *   - Noop links factory
+ *
+ * Each at-package stub only needs to handle its domain-specific response shapes.
+ * TSStub has zero dependencies on any at-package — purely generic infrastructure.
+ */
+export interface TSStubLatencyConfig {
+    /** Fixed artificial latency in ms. Ignored when `latencyMsMin`/`latencyMsMax` are set. */
+    latencyMs?: number;
+    /** Lower bound for randomised latency (ms). Pair with `latencyMsMax`. */
+    latencyMsMin?: number;
+    /** Upper bound for randomised latency (ms). Pair with `latencyMsMin`. */
+    latencyMsMax?: number;
+    /** Hang exactly this long then throw AbortError — simulates provider timeout. */
+    simulateTimeoutMs?: number;
+}
+export interface TSStubConfig extends TSStubLatencyConfig {
+    /** Throw a generic network error immediately — tests circuit breakers and retry logic. */
+    simulateNetworkError?: boolean;
+    /** Return a rate-limit exceeded response instead of processing the request. */
+    simulateRateLimitExceeded?: boolean;
+    /**
+     * Domain-specific outcome token. Stubs pass this to `TSStub.outcome(cfg, fallback)`.
+     * Common values: 'completed' | 'pending' | 'failed' | 'processing' | 'delivered' | 'bounced'
+     */
+    simulateOutcome?: string;
+    /** Failure / bounce reason text. Default: 'simulated failure'. */
+    simulateFailureReason?: string;
+    /**
+     * Fail the first N calls (per key), then succeed.
+     * Useful for testing retry policies end-to-end.
+     * Requires a `TSStubRetryCounter` per stub instance.
+     */
+    simulateFailFirstN?: number;
+    /** Signature value this stub accepts on `parseWebhook`. Default: 'stub-signature'. */
+    simulateWebhookSignature?: string;
+    /** Declared rate limit (req/sec) surfaced via `asyncContract.capabilities`. */
+    simulateRateLimitPerSecond?: number;
+    /** Declared burst capacity above the steady-state rate. */
+    simulateRateLimitBurst?: number;
+    /** Synthetic health status for stubs that implement `checkHealth()`. Default: 'healthy'. */
+    simulateHealthStatus?: 'healthy' | 'degraded' | 'unhealthy';
+    /** Prefix for generated fake access tokens. Default: 'stub-token'. */
+    simulateTokenPrefix?: string;
+    /** OAuth callback base URL returned by `buildAuthorizeUrl`. Default: 'https://stub.local/callback'. */
+    simulateCallbackBase?: string;
+}
+export interface TSStubStore<T> {
+    get(id: string): T | undefined;
+    set(id: string, value: T): void;
+    delete(id: string): boolean;
+    list(): T[];
+    entries(): Array<[string, T]>;
+    clear(): void;
+    /** Generate a sequential deterministic ID: `<prefix>-001`, `<prefix>-002`, ... */
+    nextId(prefix?: string): string;
+    size: number;
+}
+export interface TSStubRetryCounter {
+    /** Returns true (should fail) for the first `n` calls on `key`, then false. */
+    shouldFail(key: string, n: number): boolean;
+    /** Reset call counts — call in test beforeEach. */
+    reset(key?: string): void;
+}
+export declare class TSStubRateLimitError extends Error {
+    readonly code = "STUB_RATE_LIMIT_EXCEEDED";
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs?: number);
+}
+export declare class TSStub {
+    /**
+     * Delay by `cfg.latencyMs` (fixed) or a uniform random value in
+     * `[cfg.latencyMsMin, cfg.latencyMsMax]`. Abortable via `signal`.
+     * If `cfg.simulateTimeoutMs` is set, waits that long then throws AbortError.
+     */
+    static maybeDelay(cfg: TSStubLatencyConfig, signal?: AbortSignal): Promise<void>;
+    /**
+     * Call at the start of every stub method. Throws a network error or rate-limit
+     * error when the corresponding simulate flag is set.
+     * Also honours `simulateTimeoutMs` via `maybeDelay`.
+     */
+    static maybeInjectError(cfg: TSStubConfig, signal?: AbortSignal): Promise<void>;
+    /**
+     * Return `cfg.simulateOutcome ?? fallback`, cast to T.
+     * Domain stubs pass their expected outcome union as T.
+     */
+    static outcome<T extends string>(cfg: Pick<TSStubConfig, 'simulateOutcome'>, fallback: T): T;
+    static isFailed(cfg: Pick<TSStubConfig, 'simulateOutcome'>): boolean;
+    static isPending(cfg: Pick<TSStubConfig, 'simulateOutcome'>): boolean;
+    static failureReason(cfg: Pick<TSStubConfig, 'simulateFailureReason'>, fallback?: string): string;
+    /** Factory — create one per stub instance; call `reset()` in test teardown. */
+    static createRetryCounter(): TSStubRetryCounter;
+    /**
+     * Check retry counter. Returns true when the call should fail.
+     * Usage inside a stub method:
+     *   if (retry.shouldFail(operationKey, cfg.simulateFailFirstN ?? 0)) throw ...
+     */
+    static shouldFail(counter: TSStubRetryCounter, key: string, cfg: Pick<TSStubConfig, 'simulateFailFirstN'>): boolean;
+    /**
+     * Validate webhook signature against `cfg.simulateWebhookSignature`.
+     * Returns true when signatures match (or when incoming equals the default stub value).
+     */
+    static validateSignature(incoming: string | undefined, cfg: Pick<TSStubConfig, 'simulateWebhookSignature'>, defaultSignature?: string): boolean;
+    static rateLimitCapabilities(cfg: Pick<TSStubConfig, 'simulateRateLimitPerSecond' | 'simulateRateLimitBurst'>): {
+        rateLimitPerSecond?: number;
+        rateLimitBurst?: number;
+    };
+    static healthStatus(cfg: Pick<TSStubConfig, 'simulateHealthStatus'>): 'healthy' | 'degraded' | 'unhealthy';
+    /** Factory — create one store per entity type in the stub constructor. */
+    static createStore<T>(): TSStubStore<T>;
+    /** Generate a random stub ID: `stub-<prefix>-<8 hex chars>`. */
+    static id(prefix?: string): string;
+    /**
+     * Create a sequential ID generator: returns a function that yields
+     * `stub-<prefix>-001`, `stub-<prefix>-002`, ... (resets per call to this factory).
+     */
+    static seqId(prefix?: string): () => string;
+    static fakeToken(cfg?: Pick<TSStubConfig, 'simulateTokenPrefix'>): {
+        accessToken: string;
+        refreshToken: string;
+        expiresAt: number;
+    };
+    static fakeAuthUrl(cfg?: Pick<TSStubConfig, 'simulateCallbackBase'>, params?: Record<string, string>): string;
+    /**
+     * Look up `from → to` in a rate table, then try inverse, then fall back to `defaultRate`.
+     * Same logic as atexchange `Stub` driver.
+     */
+    static resolveRate(from: string, to: string, table?: Record<string, number>, defaultRate?: number): number;
+    /**
+     * Build a capability map for packages like atsocial that expose a fixed set of keys.
+     * All keys default to `'unsupported'`; `supported` overrides per key.
+     */
+    static capabilities<K extends string>(allKeys: readonly K[], supported?: Partial<Record<K, 'supported' | 'requires_review' | 'unsupported'>>): Record<K, 'supported' | 'requires_review' | 'unsupported'>;
+    /**
+     * Extract all TSStubConfig fields from a raw config object.
+     * Used in `normalizeDriverConfig` in each at-package stub.
+     */
+    static extractConfig(raw: Record<string, unknown>): Partial<TSStubConfig>;
+    /**
+     * Noop links object — used as the `protected links` property in stub drivers.
+     * scheme defaults to 'stub'.
+     */
+    static noopLinks(scheme?: string): Record<string, Record<string, string>>;
+}