@florent-uzio/custody 2.3.0 → 2.5.0

package/dist/versioning/version-guard.js

@@ -0,0 +1,181 @@
+import { CAPABILITIES } from "../models/capabilities.generated.js";
+import { CustodyError } from "../models/index.js";
+/**
+ * Thrown when a call needs a capability the resolved backend version does not
+ * support. Extends {@link CustodyError} so existing `catch (CustodyError)`
+ * handlers still catch it.
+ */
+export class UnsupportedInVersionError extends CustodyError {
+    capability;
+    kind;
+    appVersion;
+    sdkMethod;
+    constructor(args) {
+        super({
+            reason: `${args.sdkMethod} requires ${args.kind} "${args.capability}", which is not ` +
+                `available on the resolved backend version ${args.appVersion}.`,
+        });
+        this.name = "UnsupportedInVersionError";
+        this.capability = args.capability;
+        this.kind = args.kind;
+        this.appVersion = args.appVersion;
+        this.sdkMethod = args.sdkMethod;
+    }
+}
+/**
+ * Maps an XRPL operation `type` (the discriminator of `Core_XrplOperation`) to
+ * its component-schema name. The generated union members are named
+ * `Core_XrplOperation_<type>` exactly, so no lookup table is needed.
+ */
+export function xrplOperationSchema(operationType) {
+    return `Core_XrplOperation_${operationType}`;
+}
+/**
+ * Builds the capability set for an explicitly-requested app version from the
+ * bundled capability data. Throws when the version is not bundled.
+ */
+export function resolveExplicitCapabilities(apiVersion) {
+    const entry = CAPABILITIES[apiVersion];
+    if (!entry) {
+        const known = Object.keys(CAPABILITIES).join(", ");
+        throw new CustodyError({
+            reason: `Unknown apiVersion "${apiVersion}". Known versions: ${known}.`,
+        });
+    }
+    return {
+        appVersion: apiVersion,
+        endpoints: new Set(entry.endpoints),
+        schemas: new Set(entry.schemas),
+    };
+}
+/**
+ * Runtime guard that blocks calls the resolved backend version cannot serve.
+ *
+ * When constructed with no resolved capabilities it is a **pass-through**: every
+ * check is a no-op (fail-open). The backend remains the ultimate authority.
+ */
+export class VersionGuard {
+    resolved;
+    settled;
+    pending;
+    failedOpen = false;
+    warned = false;
+    resolver;
+    onFailOpen;
+    /**
+     * Construct a guard with capabilities already resolved (or `undefined` for a
+     * pass-through guard). Pass a `resolver` for lazy resolution, or use
+     * {@link VersionGuard.deferred}. `onFailOpen` runs once the first time the
+     * guard passes a call through because no version could be resolved.
+     */
+    constructor(resolved, resolver, onFailOpen) {
+        this.resolved = resolved;
+        this.resolver = resolver;
+        this.onFailOpen = onFailOpen;
+        this.settled = resolver === undefined;
+    }
+    /**
+     * Construct a guard whose capabilities are resolved lazily on first use (e.g.
+     * by fetching the live instance spec). The resolver runs at most once per
+     * successful resolution; concurrent triggers share a single invocation.
+     */
+    static deferred(resolver, onFailOpen) {
+        return new VersionGuard(undefined, resolver, onFailOpen);
+    }
+    /** Whether the guard has a resolved version and is actively gating. */
+    get isActive() {
+        return this.resolved !== undefined;
+    }
+    /**
+     * Resolve the capability set if not already resolved. Idempotent and
+     * concurrency-safe: parallel calls share one in-flight resolution. On failure
+     * the error propagates and a later call retries.
+     */
+    async ensureResolved() {
+        if (this.settled)
+            return;
+        if (!this.pending) {
+            const resolver = this.resolver;
+            this.pending = resolver().then((caps) => {
+                this.resolved = caps;
+                this.settled = true;
+            }, (error) => {
+                this.pending = undefined;
+                throw error;
+            });
+        }
+        return this.pending;
+    }
+    /** Resolves (detecting if needed) then asserts the endpoint capability. */
+    async checkEndpoint(httpMethod, pathTemplate, sdkMethod) {
+        if (await this.gatingActive()) {
+            this.assertEndpoint(httpMethod, pathTemplate, sdkMethod);
+        }
+    }
+    /** Resolves (detecting if needed) then asserts the feature capability. */
+    async checkFeature(schemaName, sdkMethod) {
+        if (await this.gatingActive()) {
+            this.assertFeature(schemaName, sdkMethod);
+        }
+    }
+    /**
+     * Whether gating is active for the call path. Resolves the version on first
+     * use; if no version can be resolved — detection failed, or the guard is a
+     * pass-through — it **fails open**: returns `false` (call passes through) and
+     * fires `onFailOpen` once. The unresolved state is cached, so detection is
+     * not re-attempted on every call. `ensureResolved`/`ready()` keep surfacing
+     * detection errors independently.
+     */
+    async gatingActive() {
+        if (this.failedOpen)
+            return false;
+        try {
+            await this.ensureResolved();
+        }
+        catch {
+            return this.enterFailOpen();
+        }
+        if (!this.resolved)
+            return this.enterFailOpen();
+        return true;
+    }
+    enterFailOpen() {
+        this.failedOpen = true;
+        if (!this.warned) {
+            this.warned = true;
+            this.onFailOpen?.();
+        }
+        return false;
+    }
+    /**
+     * Asserts the resolved version serves `METHOD /pathTemplate`.
+     * @param sdkMethod - Label for the error (defaults to the HTTP descriptor).
+     */
+    assertEndpoint(httpMethod, pathTemplate, sdkMethod) {
+        if (!this.resolved)
+            return;
+        const capability = `${httpMethod.toUpperCase()} ${pathTemplate}`;
+        if (!this.resolved.endpoints.has(capability)) {
+            throw new UnsupportedInVersionError({
+                capability,
+                kind: "endpoint",
+                appVersion: this.resolved.appVersion,
+                sdkMethod: sdkMethod ?? capability,
+            });
+        }
+    }
+    /** Asserts the resolved version defines the component schema `schemaName`. */
+    assertFeature(schemaName, sdkMethod) {
+        if (!this.resolved)
+            return;
+        if (!this.resolved.schemas.has(schemaName)) {
+            throw new UnsupportedInVersionError({
+                capability: schemaName,
+                kind: "feature",
+                appVersion: this.resolved.appVersion,
+                sdkMethod,
+            });
+        }
+    }
+}
+//# sourceMappingURL=version-guard.js.map

package/dist/versioning/version-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-guard.js","sourceRoot":"","sources":["../../src/versioning/version-guard.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@florent-uzio/custody",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "An SDK to interact with the Ripple Custody API",
   "keywords": [
     "Ripple Custody",
@@ -36,8 +36,9 @@
     "check-format": "prettier --check .",
     "ci": "npm run build && npm run check-format && npm run test",
     "dev": "vitest",
+    "fetch:openapi-spec": "node ./scripts/fetch-openapi-release.mjs",
     "format": "prettier --write .",
-    "generate:custody-types": "npx openapi-typescript ./openapi/Ripple-Custody-v1-OpenAPI.json -o ./src/models/custody-types.ts && prettier --write ./src/models/custody-types.ts",
+    "generate:custody-types": "node ./scripts/generate-custody-types/generate.mjs && prettier --write ./src/models/custody-types.ts ./src/models/capabilities.generated.ts",
     "local-release": "changeset version && changeset publish",
     "prepare": "npm run build",
     "release": "changeset publish",
@@ -64,8 +65,8 @@
     "@vitest/ui": "^3.1.4",
     "dotenv": "^16.4.7",
     "openapi-typescript": "^7.9.1",
-    "prettier": "^3.5.3",
-    "prettier-plugin-organize-imports": "^4.1.0",
+    "prettier": "^3.9.5",
+    "prettier-plugin-organize-imports": "^4.3.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.2",
     "vitest": "^3.1.4"