@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/cjs/near-intents-conformance.d.ts

@@ -0,0 +1,85 @@
+/**
+ * One way a payload departs from the shape the parsers were written against.
+ *
+ * `found` is a description rather than the value itself, so a finding can be
+ * printed in a continuous-integration log without carrying an address, an
+ * amount or anything else from a real response into it.
+ */
+export type NearIntentsShapeFinding = {
+    /** Where in the payload, as a dotted path from the root. */
+    readonly path: string;
+    /** What the parsers require there. */
+    readonly expected: string;
+    /** What was there instead, described rather than quoted. */
+    readonly found: string;
+};
+/**
+ * Checks a `POST /v0/quote` answer against everything the quote parsers read.
+ *
+ * THE DOLLAR FIGURES ARE CHECKED THOUGH THE PARSER TOLERATES THEIR ABSENCE.
+ * `parseNearIntentsQuote` turns a missing `amountInUsd` into null and carries
+ * on, which is right for a quote and wrong for a conformance check: losing the
+ * dollar figure leaves the reader a route with no price beside it, and nothing
+ * else in the system would report that the service stopped sending one.
+ *
+ * @param payload - the raw JSON body the service answered with
+ * @param options.expectDepositAddress - true for an executable (`dry: false`)
+ *   answer, false for a dry one. A dry answer omits the deposit address by
+ *   design, so requiring it there would report a finding on a healthy service
+ * @returns every departure from the expected shape; empty means conformant
+ */
+export declare const nearIntentsQuoteShapeFindings: (payload: unknown, { expectDepositAddress }: {
+    expectDepositAddress: boolean;
+}) => readonly NearIntentsShapeFinding[];
+/**
+ * Checks a `GET /v0/tokens` answer, including the chain names we map by hand.
+ *
+ * AN UNMAPPED CHAIN NAME IS THE DRIFT MOST LIKELY TO HAPPEN AND LEAST LIKELY
+ * TO BE NOTICED. `chainIdByNearIntentsChain` is a hand-written table, and
+ * `findNearIntentsAsset` matches through it — so if the service renames a
+ * chain or adds one, every asset on that chain becomes invisible to this
+ * repository while the asset list parses perfectly and every test stays green.
+ * The names are reported rather than the assets, because a new chain we do not
+ * carry is ordinary and a renamed chain we DO carry is the emergency.
+ *
+ * @param payload - the raw JSON body from the asset endpoint
+ * @param options.requiredChains - the service's own names for the chains this
+ *   repository must keep reaching. A name missing from the answer means the
+ *   service renamed or dropped it
+ * @returns every departure from the expected shape; empty means conformant
+ */
+export declare const nearIntentsTokenListShapeFindings: (payload: unknown, { requiredChains }: {
+    requiredChains: readonly string[];
+}) => readonly NearIntentsShapeFinding[];
+/**
+ * The service's own names for every chain this repository maps to a chain
+ * identifier, which is exactly the set whose renaming would be invisible.
+ */
+export declare const nearIntentsMappedChainNames: () => readonly string[];
+/**
+ * Checks a `GET /v0/status` answer against what the status parser reads.
+ *
+ * THE DELIVERY HASH IS NOT REQUIRED, and that is not laxity. A route awaiting
+ * its deposit has genuinely not produced one, and the captured
+ * `status-pending-deposit.json` is exactly that case — so requiring it would
+ * report a finding on a perfectly healthy in-flight transfer. What is required
+ * is that the ARRAY exists, because its absence is the difference between "no
+ * hash yet" and "the service stopped telling us where the funds landed".
+ *
+ * @param payload - the raw JSON body from the status endpoint
+ * @returns every departure from the expected shape; empty means conformant
+ */
+export declare const nearIntentsStatusShapeFindings: (payload: unknown) => readonly NearIntentsShapeFinding[];
+/**
+ * Checks a refusal body carries the message the refusal parser reads.
+ *
+ * BOTH SIZE FLOORS ARRIVE ONLY AS PROSE IN THIS FIELD. There is no code, no
+ * limits endpoint and no structured figure — `parseNearIntentsQuoteRefusal`
+ * runs a regular expression over the sentence. So if the wording changes, a
+ * refusal that should withdraw the route from the competition instead reads as
+ * `other`, and the reader waits for a bid that will never come.
+ *
+ * @param payload - the raw JSON body of a refused quote
+ * @returns every departure from the expected shape; empty means conformant
+ */
+export declare const nearIntentsRefusalShapeFindings: (payload: unknown) => readonly NearIntentsShapeFinding[];

package/dist/cjs/near-intents-conformance.js

@@ -0,0 +1,337 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nearIntentsRefusalShapeFindings = exports.nearIntentsStatusShapeFindings = exports.nearIntentsMappedChainNames = exports.nearIntentsTokenListShapeFindings = exports.nearIntentsQuoteShapeFindings = void 0;
+/**
+ * Does the live service still answer in the shape this repository parses?
+ *
+ * THIS EXISTS BECAUSE NEAR INTENTS HAS NO TEST NETWORK. The vendor states it
+ * four times in its own current material, most plainly in its list of common
+ * questions: "There is no testnet deployment and no plans for one. We
+ * recommend testing on NEAR mainnet using separate dev/test NEAR accounts."
+ * So there is no safe copy of the service to check an integration against, and
+ * the only honest substitute is a priced request against production that
+ * reserves nothing — a dry quote. See `docs/near-intents-capability-survey.md`.
+ *
+ * WHAT THIS CLOSES THAT THE FIXTURES CANNOT. `near-intents.test.ts` runs
+ * against real captures taken on 2026-09-17. A capture is a photograph: it
+ * proves the parser reads what the service sent that day, and it goes on
+ * proving that forever, including after the service stops sending it. Every
+ * parser here is tolerant by design — it returns null rather than throwing —
+ * so a field that changes type does not break a test, it removes a provider
+ * from the interface with no message anywhere. `amountOut` arriving as a
+ * number instead of a string is the whole failure: 37 green tests, and NEAR
+ * Intents silently never bids again.
+ *
+ * So these functions name every field the parsers actually depend on and
+ * report what is missing, rather than returning a normalized value. Handed a
+ * live response they answer "has production drifted away from the captures".
+ * Handed a capture they answer "is this capture still a fair stand-in".
+ *
+ * They are deliberately NOT parsers. A parser answers "can I use this"; these
+ * answer "is this what I was written against", which is a different question
+ * and needs the failures enumerated rather than collapsed into a null.
+ */
+const near_intents_js_1 = require("./near-intents.js");
+/** Which parser depends on a field, so a finding says what will break. */
+const describe = (value) => {
+    if (value === undefined) {
+        return 'absent';
+    }
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return `array of ${value.length}`;
+    }
+    return typeof value;
+};
+const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : null;
+/**
+ * Checks one field and returns a finding when it is not the required type.
+ *
+ * A base-unit amount must be a NON-EMPTY string, because that is what
+ * `parseAmount` in `near-intents.ts` requires: it refuses an empty string and
+ * refuses a number, so either one silently collapses the whole quote to null.
+ */
+const requireField = ({ container, key, path, kind, }) => {
+    const value = container[key];
+    if (kind === 'amount') {
+        if (typeof value === 'string' && value !== '') {
+            return null;
+        }
+        return { path, expected: 'a non-empty string of base units', found: describe(value) };
+    }
+    if (kind === 'number') {
+        return typeof value === 'number'
+            ? null
+            : { path, expected: 'a number', found: describe(value) };
+    }
+    if (kind === 'array') {
+        return Array.isArray(value) ? null : { path, expected: 'an array', found: describe(value) };
+    }
+    return typeof value === 'string' && value !== ''
+        ? null
+        : { path, expected: 'a non-empty string', found: describe(value) };
+};
+const compact = (findings) => findings.filter((finding) => finding !== null);
+/**
+ * Checks a `POST /v0/quote` answer against everything the quote parsers read.
+ *
+ * THE DOLLAR FIGURES ARE CHECKED THOUGH THE PARSER TOLERATES THEIR ABSENCE.
+ * `parseNearIntentsQuote` turns a missing `amountInUsd` into null and carries
+ * on, which is right for a quote and wrong for a conformance check: losing the
+ * dollar figure leaves the reader a route with no price beside it, and nothing
+ * else in the system would report that the service stopped sending one.
+ *
+ * @param payload - the raw JSON body the service answered with
+ * @param options.expectDepositAddress - true for an executable (`dry: false`)
+ *   answer, false for a dry one. A dry answer omits the deposit address by
+ *   design, so requiring it there would report a finding on a healthy service
+ * @returns every departure from the expected shape; empty means conformant
+ */
+const nearIntentsQuoteShapeFindings = (payload, { expectDepositAddress }) => {
+    const body = asRecord(payload);
+    if (!body) {
+        return [{ path: '', expected: 'an object', found: describe(payload) }];
+    }
+    const quote = asRecord(body.quote);
+    if (!quote) {
+        return [{ path: 'quote', expected: 'an object', found: describe(body.quote) }];
+    }
+    const findings = compact([
+        requireField({ container: quote, key: 'amountIn', path: 'quote.amountIn', kind: 'amount' }),
+        requireField({ container: quote, key: 'amountOut', path: 'quote.amountOut', kind: 'amount' }),
+        requireField({
+            container: quote,
+            key: 'minAmountOut',
+            path: 'quote.minAmountOut',
+            kind: 'amount',
+        }),
+        requireField({
+            container: quote,
+            key: 'withdrawFee',
+            path: 'quote.withdrawFee',
+            kind: 'amount',
+        }),
+        requireField({
+            container: quote,
+            key: 'timeEstimate',
+            path: 'quote.timeEstimate',
+            kind: 'number',
+        }),
+        requireField({
+            container: quote,
+            key: 'amountInUsd',
+            path: 'quote.amountInUsd',
+            kind: 'string',
+        }),
+        requireField({
+            container: quote,
+            key: 'amountOutUsd',
+            path: 'quote.amountOutUsd',
+            kind: 'string',
+        }),
+        expectDepositAddress
+            ? requireField({
+                container: quote,
+                key: 'depositAddress',
+                path: 'quote.depositAddress',
+                kind: 'string',
+            })
+            : null,
+    ]);
+    return [...findings, ...nearIntentsAppFeeFindings(body.quoteRequest)];
+};
+exports.nearIntentsQuoteShapeFindings = nearIntentsQuoteShapeFindings;
+/**
+ * Checks the echoed request for the surcharge a key-less caller is charged.
+ *
+ * THE SERVICE INSERTS THIS, NOT US. Nothing in this repository asks for an
+ * `appFees` entry, and the fee parser only finds the twenty-five-basis-point
+ * charge because the service writes it into the request it echoes back. If it
+ * ever stops echoing it, the charge does not stop — it disappears from the
+ * fee rows and the reader is shown a route that costs a quarter of a percent
+ * more than the interface says. That is a silent understatement of cost, so it
+ * is a finding rather than a tolerated absence.
+ */
+const nearIntentsAppFeeFindings = (quoteRequest) => {
+    const request = asRecord(quoteRequest);
+    if (!request) {
+        return [
+            { path: 'quoteRequest', expected: 'an object', found: describe(quoteRequest) },
+        ];
+    }
+    const appFees = request.appFees;
+    if (!Array.isArray(appFees)) {
+        return [{ path: 'quoteRequest.appFees', expected: 'an array', found: describe(appFees) }];
+    }
+    if (appFees.length === 0) {
+        return [
+            {
+                path: 'quoteRequest.appFees',
+                expected: 'at least one entry, the surcharge the service adds to a key-less request',
+                found: 'array of 0',
+            },
+        ];
+    }
+    return compact(appFees.map((entry, index) => {
+        const record = asRecord(entry);
+        if (!record) {
+            return {
+                path: `quoteRequest.appFees[${index}]`,
+                expected: 'an object',
+                found: describe(entry),
+            };
+        }
+        return requireField({
+            container: record,
+            key: 'fee',
+            path: `quoteRequest.appFees[${index}].fee`,
+            kind: 'number',
+        });
+    }));
+};
+/**
+ * Checks a `GET /v0/tokens` answer, including the chain names we map by hand.
+ *
+ * AN UNMAPPED CHAIN NAME IS THE DRIFT MOST LIKELY TO HAPPEN AND LEAST LIKELY
+ * TO BE NOTICED. `chainIdByNearIntentsChain` is a hand-written table, and
+ * `findNearIntentsAsset` matches through it — so if the service renames a
+ * chain or adds one, every asset on that chain becomes invisible to this
+ * repository while the asset list parses perfectly and every test stays green.
+ * The names are reported rather than the assets, because a new chain we do not
+ * carry is ordinary and a renamed chain we DO carry is the emergency.
+ *
+ * @param payload - the raw JSON body from the asset endpoint
+ * @param options.requiredChains - the service's own names for the chains this
+ *   repository must keep reaching. A name missing from the answer means the
+ *   service renamed or dropped it
+ * @returns every departure from the expected shape; empty means conformant
+ */
+const nearIntentsTokenListShapeFindings = (payload, { requiredChains }) => {
+    if (!Array.isArray(payload)) {
+        return [{ path: '', expected: 'an array of assets', found: describe(payload) }];
+    }
+    if (payload.length === 0) {
+        return [{ path: '', expected: 'at least one asset', found: 'array of 0' }];
+    }
+    const findings = [];
+    const chainsSeen = new Set();
+    payload.forEach((entry, index) => {
+        const record = asRecord(entry);
+        if (!record) {
+            findings.push({ path: `[${index}]`, expected: 'an object', found: describe(entry) });
+            return;
+        }
+        const blockchain = record.blockchain;
+        if (typeof blockchain === 'string') {
+            chainsSeen.add(blockchain);
+        }
+        findings.push(...compact([
+            requireField({
+                container: record,
+                key: 'assetId',
+                path: `[${index}].assetId`,
+                kind: 'string',
+            }),
+            requireField({
+                container: record,
+                key: 'blockchain',
+                path: `[${index}].blockchain`,
+                kind: 'string',
+            }),
+            requireField({ container: record, key: 'symbol', path: `[${index}].symbol`, kind: 'string' }),
+            requireField({
+                container: record,
+                key: 'decimals',
+                path: `[${index}].decimals`,
+                kind: 'number',
+            }),
+        ]));
+    });
+    for (const chain of requiredChains) {
+        if (chainsSeen.has(chain)) {
+            continue;
+        }
+        findings.push({
+            path: `chain "${chain}"`,
+            expected: 'present in the asset list, because chainIdByNearIntentsChain maps it',
+            found: 'absent — the service renamed or dropped it',
+        });
+    }
+    return findings;
+};
+exports.nearIntentsTokenListShapeFindings = nearIntentsTokenListShapeFindings;
+/**
+ * The service's own names for every chain this repository maps to a chain
+ * identifier, which is exactly the set whose renaming would be invisible.
+ */
+const nearIntentsMappedChainNames = () => [
+    ...near_intents_js_1.chainIdByNearIntentsChain.keys(),
+];
+exports.nearIntentsMappedChainNames = nearIntentsMappedChainNames;
+/**
+ * Checks a `GET /v0/status` answer against what the status parser reads.
+ *
+ * THE DELIVERY HASH IS NOT REQUIRED, and that is not laxity. A route awaiting
+ * its deposit has genuinely not produced one, and the captured
+ * `status-pending-deposit.json` is exactly that case — so requiring it would
+ * report a finding on a perfectly healthy in-flight transfer. What is required
+ * is that the ARRAY exists, because its absence is the difference between "no
+ * hash yet" and "the service stopped telling us where the funds landed".
+ *
+ * @param payload - the raw JSON body from the status endpoint
+ * @returns every departure from the expected shape; empty means conformant
+ */
+const nearIntentsStatusShapeFindings = (payload) => {
+    const body = asRecord(payload);
+    if (!body) {
+        return [{ path: '', expected: 'an object', found: describe(payload) }];
+    }
+    const findings = compact([
+        requireField({ container: body, key: 'status', path: 'status', kind: 'string' }),
+    ]);
+    const swapDetails = asRecord(body.swapDetails);
+    if (!swapDetails) {
+        return [
+            ...findings,
+            { path: 'swapDetails', expected: 'an object', found: describe(body.swapDetails) },
+        ];
+    }
+    return [
+        ...findings,
+        ...compact([
+            requireField({
+                container: swapDetails,
+                key: 'destinationChainTxHashes',
+                path: 'swapDetails.destinationChainTxHashes',
+                kind: 'array',
+            }),
+        ]),
+    ];
+};
+exports.nearIntentsStatusShapeFindings = nearIntentsStatusShapeFindings;
+/**
+ * Checks a refusal body carries the message the refusal parser reads.
+ *
+ * BOTH SIZE FLOORS ARRIVE ONLY AS PROSE IN THIS FIELD. There is no code, no
+ * limits endpoint and no structured figure — `parseNearIntentsQuoteRefusal`
+ * runs a regular expression over the sentence. So if the wording changes, a
+ * refusal that should withdraw the route from the competition instead reads as
+ * `other`, and the reader waits for a bid that will never come.
+ *
+ * @param payload - the raw JSON body of a refused quote
+ * @returns every departure from the expected shape; empty means conformant
+ */
+const nearIntentsRefusalShapeFindings = (payload) => {
+    const body = asRecord(payload);
+    if (!body) {
+        return [{ path: '', expected: 'an object', found: describe(payload) }];
+    }
+    return compact([
+        requireField({ container: body, key: 'message', path: 'message', kind: 'string' }),
+    ]);
+};
+exports.nearIntentsRefusalShapeFindings = nearIntentsRefusalShapeFindings;

package/dist/cjs/near-intents-route.d.ts

@@ -0,0 +1,47 @@
+import type { DeferredCrossing, RouteCandidate } from './routing/candidate.js';
+import type { RouteData } from './routing/route-data.js';
+/**
+ * Builds the two-signature route for a candidate whose aggregator cannot
+ * execute the omnibridge entry call.
+ *
+ * The result has exactly two sections, and the order carries the meaning:
+ *
+ *   1. The aggregator's leg, signed NOW. It ends with the anchor token sitting
+ *      in the reader's own wallet on the entry chain.
+ *   2. The omnibridge crossing, marked `deferred`, signed LATER by the reader.
+ *
+ * COSTS ARE SPLIT BETWEEN THE SECTIONS RATHER THAN POOLED, because a reader
+ * deciding whether to accept a second signature needs to know what each half
+ * costs. The first section's spread is the difference between the aggregator's
+ * own paid and delivered figures — both from the one answer that priced them,
+ * never from two feeds. The second section's cost is the omnibridge crossing
+ * fee, computed from the known on-chain rate.
+ *
+ * THE DELIVERED FIGURE IS AN ESTIMATE AND THE INTERFACE KNOWS IT. A route whose
+ * last section is deferred has not been quoted end to end, so
+ * `outputAmountIsUnsettled` blanks the received-amount field on the reader's
+ * behalf. The figure is still carried — the conversion route sets its estimate
+ * the same way — so the route can be ranked and compared.
+ *
+ * @param candidate - the route candidate, which must carry a `deferredCrossing`
+ * @returns the two-section route, or null when the candidate names no deferred
+ *   crossing or no omnibridge provider to perform it
+ */
+export declare const buildNearIntentsTwoStepRouteData: (candidate: RouteCandidate) => RouteData | null;
+/**
+ * Describes the anchor a two-signature route leaves the reader holding.
+ *
+ * A small constructor rather than an inline object literal at the call site,
+ * so the three fields are named and documented in one place and a caller
+ * cannot quietly pair one aggregator's amount with another's valuation.
+ *
+ * @param options.anchorToken - the entry-chain token the aggregator delivers
+ * @param options.anchorAmount - how much of it lands, in its base units
+ * @param options.anchorUsdValue - the AGGREGATOR'S own valuation of that landing
+ * @returns the deferred-crossing record, or null when no amount is known
+ */
+export declare const describeDeferredCrossing: ({ anchorToken, anchorAmount, anchorUsdValue, }: {
+    anchorToken: DeferredCrossing["anchorToken"] | null;
+    anchorAmount: bigint | null | undefined;
+    anchorUsdValue: string | null | undefined;
+}) => DeferredCrossing | null;