@kasufinance/kasu-sdk 2.5.0 → 2.6.0

package/src/domain/settlement.ts

@@ -0,0 +1,161 @@
+/**
+ * Cycles and the clearing window — the protocol's weekly clock, as numbers.
+ *
+ * Lifted verbatim from kasu-ui's `features/portfolio/lib/settlement-window.ts`
+ * and `features/lending/lib/cycle-dates.ts`. The two formatters that live
+ * beside `deriveCycleDates` there (`formatCycleDate`, `formatCycleCloseUtc`)
+ * print words and stay in the applications; everything here is unix seconds in
+ * and unix seconds out.
+ *
+ * The clearing window is the fixed 48 hours immediately preceding an epoch
+ * end. Inside it, pending requests are being processed and cannot be modified,
+ * and the countdown runs to the epoch end. Outside it, the countdown runs to
+ * the next clearing-window start.
+ *
+ * The epoch end comes straight from the chain (`nextEpochStartTimestamp`, i.e.
+ * the SDK's `getNextEpochDate`) — the same value the protocol's own
+ * `getNextClearingPeriodDate` derives from — so the window always lines up
+ * with the real weekly schedule (Tue 06:00 → Thu 06:00 UTC on Base) instead of
+ * a projected subgraph timestamp that can drift off the grid.
+ */
+
+/**
+ * Clearing-window length — a fixed 48h protocol constant. Exported so every
+ * consumer derives the window from the same number this module runs on.
+ */
+export const CLEARING_WINDOW_SECONDS = 48 * 60 * 60;
+
+/**
+ * Weekly cadence — the epoch schedule is fixed weekly (Tue → Thu UTC on Base).
+ * Used only to roll a cycle forward when a request lands inside a window that
+ * has already closed.
+ */
+const WEEK_SECONDS = 7 * 24 * 60 * 60;
+
+export type SettlementWindowState =
+    | {
+          phase: 'awaiting';
+          secondsUntilClearing: number;
+          nextClearingStart: number;
+      }
+    | { phase: 'clearing'; secondsUntilEpochEnd: number; epochEnd: number }
+    | { phase: 'unknown' };
+
+export interface SettlementWindowInput {
+    /** Now, in unix seconds. */
+    nowSeconds: number;
+    /**
+     * Authoritative epoch end, in unix seconds — the chain's
+     * `nextEpochStartTimestamp` (SDK `getNextEpochDate`). During an epoch this
+     * is in the future; it refetches to the next boundary once it rolls.
+     */
+    nextEpochStart: number;
+    /** Clearing-window length; defaults to the 48h protocol constant. */
+    clearingWindowSeconds?: number;
+}
+
+/**
+ * Which phase of the weekly cycle `nowSeconds` falls in, and how long is left
+ * of it.
+ *
+ * `'unknown'` when no epoch boundary has been loaded yet, or when the one on
+ * hand is stale (it has already elapsed — the on-chain value refetches to the
+ * next boundary shortly after rollover). A caller must render its "no cycle
+ * loaded" state there, never a zeroed countdown.
+ */
+export function computeSettlementWindow({
+    nowSeconds,
+    nextEpochStart,
+    clearingWindowSeconds = CLEARING_WINDOW_SECONDS,
+}: SettlementWindowInput): SettlementWindowState {
+    // No epoch boundary loaded yet, or a stale one that already elapsed.
+    if (nextEpochStart <= 0 || nextEpochStart <= nowSeconds) {
+        return { phase: 'unknown' };
+    }
+
+    const clearingStart = nextEpochStart - clearingWindowSeconds;
+
+    if (nowSeconds < clearingStart) {
+        return {
+            phase: 'awaiting',
+            secondsUntilClearing: clearingStart - nowSeconds,
+            nextClearingStart: clearingStart,
+        };
+    }
+
+    // nowSeconds is in [clearingStart, nextEpochStart) — inside the window.
+    return {
+        phase: 'clearing',
+        secondsUntilEpochEnd: nextEpochStart - nowSeconds,
+        epochEnd: nextEpochStart,
+    };
+}
+
+/**
+ * The next cycle boundary strictly after `nowSeconds`, in unix seconds — the
+ * cycle close (`nextEpochStart − 48h`) while the window is still open, the
+ * epoch end once we are inside it.
+ *
+ * `undefined` when there is no boundary left to wait for: no epoch boundary
+ * loaded, or a cached one that has already elapsed — the same staleness rule
+ * `computeSettlementWindow` applies before it reports `'unknown'`.
+ *
+ * Split out of the state machine because some consumers need the INSTANT
+ * rather than the phase: one to flush the cycle-dependent caches when the
+ * clock crosses it, one to move a pre-commit screen's snapshot clock at the
+ * same moment.
+ */
+export function nextCycleBoundary(
+    nextEpochStart: number | undefined,
+    nowSeconds: number,
+    clearingWindowSeconds: number = CLEARING_WINDOW_SECONDS,
+): number | undefined {
+    if (!nextEpochStart || nextEpochStart <= 0) return undefined;
+    const clearingStart = nextEpochStart - clearingWindowSeconds;
+    if (nowSeconds < clearingStart) return clearingStart;
+    if (nowSeconds < nextEpochStart) return nextEpochStart;
+    return undefined;
+}
+
+export interface CycleDates {
+    /** Unix seconds — the next cycle close (clearing-window start). */
+    close: number;
+    /** Unix seconds — the outcome-confirmed-by boundary (close + 48h). */
+    outcome: number;
+}
+
+/**
+ * The cycle-close and outcome dates for a request submitted `now`.
+ *
+ * - The cycle "closes" (stops accepting requests, starts processing) at the
+ *   start of the 48h clearing window, i.e. 48h before the epoch end.
+ * - Processing takes up to 48h, so the outcome is confirmed by the epoch end
+ *   (close + 48h).
+ *
+ * Returns `null` when the epoch boundary is not available or is stale — a
+ * caller then omits the dates entirely (omit, don't stub).
+ *
+ * The common case is a request submitted OUTSIDE the clearing window: the
+ * close is `nextEpochStart − 48h` and the outcome is `nextEpochStart`. When
+ * the request lands INSIDE the current clearing window (that close is already
+ * in the past), it queues for the NEXT weekly cycle, so the close is advanced
+ * by whole weeks until it is in the future.
+ */
+export function deriveCycleDates(
+    nextEpochStart: number | undefined,
+    nowSeconds: number,
+): CycleDates | null {
+    // No boundary loaded, or a stale one that already elapsed — the same
+    // staleness rule as `computeSettlementWindow`.
+    if (!nextEpochStart || nextEpochStart <= nowSeconds) return null;
+
+    let close = nextEpochStart - CLEARING_WINDOW_SECONDS;
+    let outcome = nextEpochStart;
+    // Inside the current clearing window the close already passed; a request
+    // now is queued for the next weekly cycle.
+    while (close <= nowSeconds) {
+        close += WEEK_SECONDS;
+        outcome += WEEK_SECONDS;
+    }
+    return { close, outcome };
+}

package/src/domain/wallet-errors.test.ts

@@ -0,0 +1,100 @@
+import { isUnpredictableGas, isUserRejected } from './wallet-errors';
+
+/**
+ * `isUserRejected` cases ported from kasu-ui
+ * `src/lib/web3/is-user-rejected.test.ts`. `isUnpredictableGas` had no test in
+ * kasu-mobile; one is written here.
+ */
+
+describe('isUserRejected', () => {
+    it('detects EIP-1193 numeric code 4001', () => {
+        expect(isUserRejected({ code: 4001, message: 'whatever' })).toBe(true);
+    });
+
+    it('detects ACTION_REJECTED string code (ethers v5)', () => {
+        expect(
+            isUserRejected({ code: 'ACTION_REJECTED', message: 'rejected' }),
+        ).toBe(true);
+    });
+
+    it('detects "User rejected" message string', () => {
+        expect(isUserRejected(new Error('User rejected the request'))).toBe(
+            true,
+        );
+    });
+
+    it('detects "User denied" message string', () => {
+        expect(
+            isUserRejected(new Error('User denied transaction signature')),
+        ).toBe(true);
+    });
+
+    it('detects the ethers ACTION_REJECTED marker in a message', () => {
+        expect(
+            isUserRejected(new Error('transaction failed: ACTION_REJECTED')),
+        ).toBe(true);
+    });
+
+    it('is case-insensitive', () => {
+        expect(isUserRejected(new Error('user REJECTED the request'))).toBe(
+            true,
+        );
+    });
+
+    it('returns false for unrelated errors', () => {
+        expect(isUserRejected(new Error('Network error'))).toBe(false);
+        expect(isUserRejected(new Error('Insufficient funds'))).toBe(false);
+    });
+
+    it('returns false for null / undefined', () => {
+        expect(isUserRejected(null)).toBe(false);
+        expect(isUserRejected(undefined)).toBe(false);
+    });
+
+    it('handles non-Error throwables', () => {
+        expect(isUserRejected('user rejected')).toBe(true);
+        expect(isUserRejected('something else')).toBe(false);
+    });
+
+    it('is not fooled by a numeric code that only looks like 4001', () => {
+        expect(isUserRejected({ code: '4001' })).toBe(false);
+        expect(isUserRejected({ code: 4002 })).toBe(false);
+    });
+});
+
+describe('isUnpredictableGas', () => {
+    it('detects the ethers v5 gas-estimation revert code', () => {
+        expect(isUnpredictableGas({ code: 'UNPREDICTABLE_GAS_LIMIT' })).toBe(
+            true,
+        );
+    });
+
+    it('does not fire on a user rejection', () => {
+        expect(isUnpredictableGas({ code: 'ACTION_REJECTED' })).toBe(false);
+        expect(isUnpredictableGas({ code: 4001 })).toBe(false);
+    });
+
+    it('does not fire on the code appearing only in a message', () => {
+        // The code is the signal; a message mentioning it is not one, or a
+        // logged error string would be mistaken for a revert.
+        expect(
+            isUnpredictableGas(new Error('UNPREDICTABLE_GAS_LIMIT')),
+        ).toBe(false);
+        expect(isUnpredictableGas('UNPREDICTABLE_GAS_LIMIT')).toBe(false);
+    });
+
+    it('returns false for null / undefined and for unrelated errors', () => {
+        expect(isUnpredictableGas(null)).toBe(false);
+        expect(isUnpredictableGas(undefined)).toBe(false);
+        expect(isUnpredictableGas(new Error('Network error'))).toBe(false);
+    });
+
+    it('reads the code off an ethers error object', () => {
+        const err = Object.assign(new Error('cannot estimate gas'), {
+            code: 'UNPREDICTABLE_GAS_LIMIT',
+            reason: 'execution reverted: ERC20: insufficient allowance',
+        });
+        expect(isUnpredictableGas(err)).toBe(true);
+        expect(isUserRejected(err)).toBe(false);
+    });
+});

package/src/domain/wallet-errors.ts

@@ -0,0 +1,56 @@
+/**
+ * Wallet and RPC error predicates — pure functions over `unknown`.
+ *
+ * Every consumer has to tell three things apart when a write fails: the lender
+ * changed their mind, the call would revert, and everything else. The first
+ * two must never be reported as a failure the lender should retry or contact
+ * support about, and each wallet spells them differently, so the shapes are
+ * enumerated once here.
+ *
+ * Lifted from kasu-ui's `src/lib/web3/is-user-rejected.ts` and kasu-mobile's
+ * `src/features/lending/lib/errors.ts`.
+ */
+
+/**
+ * Did the lender reject the request in their wallet?
+ *
+ * Providers surface a rejection in different shapes:
+ *   - MetaMask and most EIP-1193 wallets: `code: 4001`
+ *   - WalletConnect and some Privy paths: `Error('User rejected the request')`
+ *   - ethers v5 wraps it as `ACTION_REJECTED`
+ *   - Coinbase Wallet sometimes: `code: 'ACTION_REJECTED'` as a string
+ *
+ * This is kasu-ui's implementation verbatim. kasu-mobile's copy additionally
+ * reads a nested `error.code` / `error.message`, an ethers `reason`, and the
+ * words "request rejected" / "declined"; a consumer that needs those shapes
+ * should keep its own check on top rather than assume they are covered here.
+ */
+export function isUserRejected(err: unknown): boolean {
+    if (!err) return false;
+    if (typeof err === 'object') {
+        const code = (err as { code?: unknown }).code;
+        if (code === 4001 || code === 'ACTION_REJECTED') return true;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    const lower = msg.toLowerCase();
+    return (
+        lower.includes('user rejected') ||
+        lower.includes('user denied') ||
+        lower.includes('rejected the request') ||
+        lower.includes('action_rejected')
+    );
+}
+
+/**
+ * Did the wallet or RPC signal that the on-chain call would revert?
+ *
+ * ethers v5 raises `UNPREDICTABLE_GAS_LIMIT` when gas estimation reverts —
+ * most often an underlying `transferFrom` failing on an insufficient balance
+ * or allowance. Distinct from a rejection: nothing was refused by the lender,
+ * the transaction simply cannot succeed as composed, so the caller should
+ * re-check its preconditions rather than invite a retry.
+ */
+export function isUnpredictableGas(err: unknown): boolean {
+    if (!err || typeof err !== 'object') return false;
+    return (err as { code?: unknown }).code === 'UNPREDICTABLE_GAS_LIMIT';
+}

package/src/facade/chain-configs.ts

@@ -151,8 +151,14 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
             ClearingCoordinator: '',
             ExternalTVL: '',
         },
+        // The frozen Plume history is indexed on the LEGACY Goldsky project,
+        // not the one the live chains use: the same path under the current
+        // project 404s. Verified 2026-09-05 — this URL answers
+        // `{ lendingPools { id name } }` with the three Plume pools; the
+        // current-project spelling returns HTTP 404. Note the `/gn` suffix,
+        // which the current project's URLs do not carry.
         subgraphUrl:
-            'https://api.goldsky.com/api/public/project_cmgzlpxm300765np2a19421om/subgraphs/kasu-plume/prod',
+            'https://api.goldsky.com/api/public/project_cm9t3064xeuyn01tgctdo3c17/subgraphs/kasu-plume/prod/gn',
         directusUrl: 'https://kasu-finance.directus.app/',
         unusedPoolIds: [],
         poolMetadataMapping: undefined,

package/src/facade/facade.test.ts

@@ -3,6 +3,13 @@
  * here from `src/tests/` so it runs beside the code it covers, and so the
  * opt-in `LIVE_TESTS` gate on `src/tests/` does not take it out of CI.
  */
+import { DataService } from '../services/DataService/data-service';
+import { NO_DIRECTUS_URL_MESSAGE } from '../services/DataService/directus-client';
+import { Portfolio } from '../services/Portfolio/portfolio';
+import { UserRequestStatus } from '../services/UserLending/subgraph-types';
+import { UserRequest } from '../services/UserLending/types';
+import { UserLending } from '../services/UserLending/user-lending';
+
 import { CHAIN_CONFIGS } from './chain-configs';
 import { DepositsFacade } from './deposits';
 import { Kasu } from './kasu';
@@ -52,6 +59,18 @@ describe('CHAIN_CONFIGS', () => {
         }
     });
 
+    it('plume points at the LEGACY goldsky project its frozen history is on', () => {
+        // Plume was indexed before the live chains moved to the current
+        // project; the same path under that project returns HTTP 404, so the
+        // retired deployment's history is only readable at this spelling —
+        // note the `/gn` suffix the current project's URLs do not carry.
+        const projectOf = (url: string): string => url.split('/')[5] ?? '';
+        expect(projectOf(CHAIN_CONFIGS.plume.subgraphUrl)).not.toBe(
+            projectOf(CHAIN_CONFIGS.base.subgraphUrl),
+        );
+        expect(CHAIN_CONFIGS.plume.subgraphUrl.endsWith('/gn')).toBe(true);
+    });
+
     it('xdc should have poolMetadataMapping', () => {
         const mapping = CHAIN_CONFIGS.xdc.poolMetadataMapping;
         expect(mapping).toBeDefined();
@@ -131,6 +150,35 @@ describe('Kasu.create()', () => {
         expect(kasu).toBeInstanceOf(Kasu);
     });
 
+    it('constructs without a directusUrl — on-chain data does not need one', () => {
+        // `createDirectus('')` throws `Invalid URL`, so an SDK configured
+        // without the (documented-optional) CMS URL used to be
+        // unconstructable rather than merely CMS-less.
+        const kasu = Kasu.create({
+            chain: 'base',
+            signerOrProvider: mockProvider as never,
+            configOverrides: { directusUrl: '' },
+        });
+
+        expect(kasu).toBeInstanceOf(Kasu);
+        expect(kasu.services.DataService).toBeDefined();
+        expect(kasu.services.UserLending).toBeDefined();
+    });
+
+    it('refuses a CMS-only call clearly when no directusUrl is configured', async () => {
+        const kasu = Kasu.create({
+            chain: 'base',
+            signerOrProvider: mockProvider as never,
+            configOverrides: { directusUrl: '' },
+        });
+
+        // A sentence naming what to configure, not a null dereference thrown
+        // from inside the vendor SDK.
+        await expect(
+            kasu.services.DataService.getPlatformOverview(),
+        ).rejects.toThrow(NO_DIRECTUS_URL_MESSAGE);
+    });
+
     it('should expose the underlying KasuSdk via .services', () => {
         const kasu = Kasu.create({
             chain: 'base',
@@ -201,6 +249,59 @@ describe('StrategiesFacade.calculateDepositLimits()', () => {
     });
 });
 
+// ---------------------------------------------------------------------------
+// PortfolioFacade.getRequestStates()
+// ---------------------------------------------------------------------------
+
+describe('PortfolioFacade.getRequestStates()', () => {
+    it('maps the transaction history through deriveRequestState', async () => {
+        const requests: UserRequest[] = [
+            makeUserRequest({ id: 'req-1' }),
+            makeUserRequest({
+                id: 'req-2',
+                requestType: 'Withdrawal',
+                status: UserRequestStatus.PROCESSED,
+                canCancel: false,
+                acceptedAmount: '100',
+            }),
+        ];
+        const userLending = {
+            getCurrentEpoch: (): Promise<string> => Promise.resolve('42'),
+            getUserRequests: (): Promise<UserRequest[]> =>
+                Promise.resolve(requests),
+        } as unknown as UserLending;
+
+        const facade = new PortfolioFacade(
+            {} as unknown as DataService,
+            userLending,
+            {} as unknown as Portfolio,
+        );
+
+        const states = await facade.getRequestStates('0xuser');
+
+        expect(states.map((s) => s.id)).toEqual(['req-1', 'req-2']);
+        expect(states[0].statusCode).toBe('pending');
+        expect(states[0].amount).toBe(100);
+        expect(states[1].statusCode).toBe('complete');
+        expect(states[1].amount).toBe(-100);
+    });
+
+    it('returns an empty list for a wallet with no history', async () => {
+        const userLending = {
+            getCurrentEpoch: (): Promise<string> => Promise.resolve('42'),
+            getUserRequests: (): Promise<UserRequest[]> => Promise.resolve([]),
+        } as unknown as UserLending;
+
+        const facade = new PortfolioFacade(
+            {} as unknown as DataService,
+            userLending,
+            {} as unknown as Portfolio,
+        );
+
+        await expect(facade.getRequestStates('0xuser')).resolves.toEqual([]);
+    });
+});
+
 // ---------------------------------------------------------------------------
 // Type exports — verify key facade types are importable
 // ---------------------------------------------------------------------------
@@ -248,3 +349,26 @@ function makeTranche(raw: {
         },
     } as never;
 }
+
+
+function makeUserRequest(overrides: Partial<UserRequest> = {}): UserRequest {
+    return {
+        id: 'req-1',
+        userId: '0xuser',
+        lendingPool: { id: '0xpool', name: 'Pool', tranches: [{ orderId: '0' }] },
+        requestType: 'Deposit',
+        trancheId: '0xtranche',
+        trancheName: 'Senior',
+        requestedAmount: '100',
+        acceptedAmount: '0',
+        rejectedAmount: '0',
+        timestamp: 1_700_000_000,
+        status: UserRequestStatus.REQUESTED,
+        canCancel: true,
+        events: [],
+        nftId: '',
+        apy: '0',
+        fixedTermConfig: undefined,
+        ...overrides,
+    };
+}

package/src/facade/user-portfolio.ts

@@ -1,5 +1,6 @@
 import { Provider } from '@ethersproject/providers';
 
+import { deriveRequestState, RequestState } from '../domain/requests';
 import { DataService } from '../services/DataService/data-service';
 import { Portfolio } from '../services/Portfolio/portfolio';
 import { UserRequest } from '../services/UserLending/types';
@@ -70,4 +71,27 @@ export class PortfolioFacade {
             currentEpoch,
         );
     }
+
+    /**
+     * The same history, already derived into `RequestState` rows — status
+     * code, kind, signed amount, the cancelled-amount recovery, the bundled
+     * submission count and the cycle-open signal.
+     *
+     * ```ts
+     * const rows = await kasu.portfolio.getRequestStates('0xUser...');
+     * rows.filter((r) => r.statusCode === 'pending');
+     * ```
+     *
+     * Every application derives this from `getTransactionHistory` anyway, and
+     * the derivation is the part they were each getting subtly differently.
+     * Words are still the caller's: render `statusCode` in your own
+     * vocabulary, and call `getTrancheDisplayName` on `trancheName` at the
+     * view boundary.
+     */
+    async getRequestStates(
+        userAddress: `0x${string}`,
+    ): Promise<RequestState[]> {
+        const requests = await this.getTransactionHistory(userAddress);
+        return requests.map(deriveRequestState);
+    }
 }

package/src/index.ts

@@ -55,6 +55,8 @@ export type {
     PlatformOverviewDirectus,
 } from './services/DataService/directus-types';
 
+export { NO_DIRECTUS_URL_MESSAGE } from './services/DataService/directus-client';
+
 // ---------------------------------------------------------------------------
 // Re-export facade (high-level integrator API)
 // ---------------------------------------------------------------------------

package/src/services/DataService/data-service.ts

@@ -1,13 +1,4 @@
-import {
-    authentication,
-    AuthenticationClient,
-    createDirectus,
-    DirectusClient,
-    readItems,
-    readSingleton,
-    rest,
-    RestClient,
-} from '@directus/sdk';
+import { readItems, readSingleton } from '@directus/sdk';
 import { Provider } from '@ethersproject/abstract-provider';
 import { Signer } from 'ethers';
 import { formatUnits } from 'ethers/lib/utils';
@@ -23,9 +14,12 @@ import { getSystemVariablesQuery } from '../Locking/queries';
 import { SystemVariables } from '../Locking/types';
 import { filterArray } from '../shared';
 
+import {
+    createDirectusClient,
+    KasuDirectusClient,
+} from './directus-client';
 import {
     BadAndDoubtfulDebtsItems,
-    DirectusSchema,
     FinancialReportingDocumentsItemsDirectus,
     KeyCreditMetricsDirectus,
     NftBoostDirectus,
@@ -67,9 +61,7 @@ import {
 export class DataService {
     private readonly _graph: GraphQLClient;
     private readonly _externalTvlAbi: KasuPoolExternalTVLAbi;
-    private readonly _directus: DirectusClient<DirectusSchema> &
-        AuthenticationClient<DirectusSchema> &
-        RestClient<DirectusSchema>;
+    private readonly _directus: KasuDirectusClient;
     private _directusPoolOverview: PoolOverviewDirectus[] | undefined;
 
     constructor(
@@ -82,16 +74,7 @@ export class DataService {
         );
         this._graph = new GraphQLClient(_kasuConfig.subgraphUrl);
 
-        if (_kasuConfig.directusUrl) {
-            this._directus = createDirectus<DirectusSchema>(
-                _kasuConfig.directusUrl,
-            )
-                .with(authentication())
-                .with(rest());
-        } else {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
-            this._directus = null as any;
-        }
+        this._directus = createDirectusClient(_kasuConfig.directusUrl);
     }
 
     private getUrlFromFile(fileName: string): string {

package/src/services/DataService/directus-client.ts

@@ -0,0 +1,54 @@
+import {
+    authentication,
+    AuthenticationClient,
+    createDirectus,
+    DirectusClient,
+    rest,
+    RestClient,
+} from '@directus/sdk';
+
+import { DirectusSchema } from './directus-types';
+
+/** The Directus client shape both services hold. */
+export type KasuDirectusClient = DirectusClient<DirectusSchema> &
+    AuthenticationClient<DirectusSchema> &
+    RestClient<DirectusSchema>;
+
+/**
+ * The error a CMS-only call raises on a deployment configured without
+ * Directus. Named so a caller can match on it rather than on the message.
+ */
+export const NO_DIRECTUS_URL_MESSAGE =
+    'Kasu: this call needs Directus, but the SDK was configured without a ' +
+    '`directusUrl`. On-chain data (pools, tranches, positions, requests) ' +
+    'works without one; CMS content does not.';
+
+/**
+ * Build the Directus client, or a stand-in that refuses clearly.
+ *
+ * `directusUrl` is documented optional, and most of the SDK genuinely does not
+ * need it — pools, tranches, positions and request history all come from the
+ * subgraph and the chain. But `createDirectus('')` throws `Invalid URL` inside
+ * the constructor, so omitting the URL used to make the whole SDK
+ * unconstructable rather than merely CMS-less.
+ *
+ * With no URL, the services skip Directus where they can degrade (pool
+ * descriptions, images and Directus pool names simply do not appear, and the
+ * raw subgraph names are used instead), and a call that exists ONLY to read
+ * CMS content rejects with `NO_DIRECTUS_URL_MESSAGE` — a sentence that says
+ * what to configure, rather than a `null` dereference thrown from inside a
+ * vendor SDK.
+ */
+export function createDirectusClient(directusUrl: string): KasuDirectusClient {
+    if (directusUrl) {
+        return createDirectus<DirectusSchema>(directusUrl)
+            .with(authentication())
+            .with(rest());
+    }
+    const refuse = (): never => {
+        throw new Error(NO_DIRECTUS_URL_MESSAGE);
+    };
+    // A stand-in, not a client: every entry point the services use goes
+    // through `request`, so refusing there covers all of them.
+    return { request: refuse } as unknown as KasuDirectusClient;
+}