@acta-markets/ts-sdk 0.0.21-beta → 0.0.23-beta

package/dist/ws/auth.d.ts

@@ -6,6 +6,9 @@
  * - Client signs UTF-8 bytes of that text and responds:
  *   `AuthChallenge { challenge, signature: base58(ed25519(utf8(challenge))), pubkey }`
  *
+ * The same `signMessage` primitive is reused for any UTF-8-bytes signing
+ * (e.g. `acta:redeem:v1:{pubkey}:{code}` for invite redemption).
+ *
  * Source of truth (server):
  * - rust-backend/rfq-server/src/server/ws.rs
  * - rust-backend/rfq-server/src/session/handler.rs
@@ -13,8 +16,8 @@
 export interface AuthProvider {
     /** Base58-encoded public key (address). */
     getPublicKey(): Promise<string>;
-    /** Base58-encoded ed25519 signature over UTF-8 bytes of the challenge text. */
-    signChallenge(challenge: string): Promise<string>;
+    /** Base58-encoded ed25519 signature over UTF-8 bytes of the message. */
+    signMessage(message: string): Promise<string>;
 }
 /**
  * Auth provider backed by a `CryptoKeyPair`.
@@ -31,7 +34,7 @@ export declare class KeypairAuthProvider implements AuthProvider {
     /** Create from Solana CLI keypair JSON (array of numbers). */
     static fromJson(json: number[] | string): Promise<KeypairAuthProvider>;
     getPublicKey(): Promise<string>;
-    signChallenge(challenge: string): Promise<string>;
+    signMessage(message: string): Promise<string>;
 }
 /**
  * Wallet-like provider (browser wallets, custom signers, etc.)
@@ -43,7 +46,7 @@ export declare class WalletAuthProvider implements AuthProvider {
     private readonly wallet;
     constructor(wallet: WalletLike);
     getPublicKey(): Promise<string>;
-    signChallenge(challenge: string): Promise<string>;
+    signMessage(message: string): Promise<string>;
 }
 export type WalletLike = {
     /** Preferred: base58 address string. */
@@ -60,8 +63,8 @@ export type WalletLike = {
  */
 export declare class CustomAuthProvider implements AuthProvider {
     private readonly getPublicKeyFn;
-    private readonly signChallengeFn;
-    constructor(getPublicKey: () => Promise<string>, signChallenge: (challenge: string) => Promise<string>);
+    private readonly signMessageFn;
+    constructor(getPublicKey: () => Promise<string>, signMessage: (message: string) => Promise<string>);
     getPublicKey(): Promise<string>;
-    signChallenge(challenge: string): Promise<string>;
+    signMessage(message: string): Promise<string>;
 }

package/dist/ws/auth.js

@@ -6,6 +6,9 @@
  * - Client signs UTF-8 bytes of that text and responds:
  *   `AuthChallenge { challenge, signature: base58(ed25519(utf8(challenge))), pubkey }`
  *
+ * The same `signMessage` primitive is reused for any UTF-8-bytes signing
+ * (e.g. `acta:redeem:v1:{pubkey}:{code}` for invite redemption).
+ *
  * Source of truth (server):
  * - rust-backend/rfq-server/src/server/ws.rs
  * - rust-backend/rfq-server/src/session/handler.rs
@@ -49,9 +52,9 @@ export class KeypairAuthProvider {
     async getPublicKey() {
         return this.address;
     }
-    async signChallenge(challenge) {
-        const challengeBytes = utf8ToBytes(challenge);
-        const signatureBytes = await signBytes(this.privateKey, challengeBytes);
+    async signMessage(message) {
+        const messageBytes = utf8ToBytes(message);
+        const signatureBytes = await signBytes(this.privateKey, messageBytes);
         return bytesToBase58(signatureBytes);
     }
 }
@@ -72,10 +75,10 @@ export class WalletAuthProvider {
             throw new Error("Wallet not connected (missing public key)");
         return pk;
     }
-    async signChallenge(challenge) {
-        const challengeBytes = utf8ToBytes(challenge);
+    async signMessage(message) {
+        const messageBytes = utf8ToBytes(message);
         // Some wallet APIs expect a mutable `Uint8Array`; codecs return `ReadonlyUint8Array`.
-        const sig = await this.wallet.signMessage(new Uint8Array(challengeBytes));
+        const sig = await this.wallet.signMessage(new Uint8Array(messageBytes));
         return bytesToBase58(sig);
     }
 }
@@ -84,15 +87,15 @@ export class WalletAuthProvider {
  */
 export class CustomAuthProvider {
     getPublicKeyFn;
-    signChallengeFn;
-    constructor(getPublicKey, signChallenge) {
+    signMessageFn;
+    constructor(getPublicKey, signMessage) {
         this.getPublicKeyFn = getPublicKey;
-        this.signChallengeFn = signChallenge;
+        this.signMessageFn = signMessage;
     }
     async getPublicKey() {
         return this.getPublicKeyFn();
     }
-    async signChallenge(challenge) {
-        return this.signChallengeFn(challenge);
+    async signMessage(message) {
+        return this.signMessageFn(message);
     }
 }

package/dist/ws/client.d.ts

@@ -2,7 +2,7 @@
 import type { AuthProvider } from "./auth";
 import type { SignerLike } from "../chain/orders";
 import type { Address } from "@solana/addresses";
-import type { ActiveRfqInfo, ChainEventMessage, EarnSummaryData, TokenMarketsInfoData, GlobalStats, MarketDescriptorInfo, MarketInfo, MyActiveRfqInfo, MyActiveRfqsMessage, OrderStatusMessage, PositionInfo, QuoteAcknowledgedMessage, QuoteBestStatusMessage, QuoteCancelledMessage, QuoteMessage, QuoteRefreshRequestedMessage, QuoteOutbidMessage, QuoteReceivedMessage, QuoteSelectedMessage, QuotesUpdateMessage, RfqBroadcastMessage, RfqClosedMessage, RfqCreatedMessage, RfqSkippedMessage, RfqRequestMessage, RfqAvailableAgainMessage, QuoteExpiredMessage, QuoteFilledMessage, IndicativePricesMessage, IndicativePricesRequestMessage, IndicativePricesResponseMessage, GetIndicativePricesMessage, MakerBalancesMessage, MakerMarketsMessage, MakerPositionsMessage, MyCapsMessage, MyQuotesMessage, MyTradesMessage, RequestId, ServerError, ServerMessage, SnapshotMessage, StatsDelta, SubscriptionsMessage, TokenInfo, TradeInfo, UuidString, VersionMismatchMessage, WelcomeMessage, WsChannel } from "./types";
+import type { ActiveRfqInfo, ChainEventMessage, EarnSummaryData, TokenMarketsInfoData, GlobalStats, MarketDescriptorInfo, MarketInfo, MyActiveRfqInfo, MyActiveRfqsMessage, OrderStatusMessage, PositionInfo, QuoteAcknowledgedMessage, QuoteBestStatusMessage, QuoteCancelledMessage, QuoteMessage, ReplaceQuoteMessage, QuoteRefreshRequestedMessage, QuoteOutbidMessage, QuoteReceivedMessage, QuoteSelectedMessage, QuotesUpdateMessage, RfqBroadcastMessage, RfqClosedMessage, RfqCreatedMessage, RfqSkippedMessage, RfqRequestMessage, RfqAvailableAgainMessage, QuoteExpiredMessage, QuoteFilledMessage, IndicativePricesMessage, IndicativePricesRequestMessage, IndicativePricesResponseMessage, GetIndicativePricesMessage, MakerBalancesMessage, MakerMarketsMessage, MakerPositionsMessage, MyCapsMessage, MyQuotesMessage, MyTradesMessage, RequestId, ServerError, ServerMessage, SnapshotMessage, StatsDelta, SubscriptionsMessage, TokenInfo, TradeInfo, UuidString, VersionMismatchMessage, WelcomeMessage, WsChannel, InviteRedeemedData, ReferralCodeClaimedData, MyReferralInfoData } from "./types";
 export type ConnectionState = "disconnected" | "connecting" | "authenticating" | "authenticated" | "error";
 export type ClientRole = "taker" | "maker";
 export type PendingMessagesOverflowPolicy = "drop_oldest" | "drop_newest" | "throw";
@@ -145,6 +145,10 @@ export type ActaWsClientEvents = {
     positionSettled: (event: Extract<ChainEventMessage, {
         event_type: "PositionSettled";
     }>) => void;
+    requireInvite: () => void;
+    inviteRedeemed: (data: InviteRedeemedData) => void;
+    referralCodeClaimed: (data: ReferralCodeClaimedData) => void;
+    myReferralInfo: (data: MyReferralInfoData) => void;
 };
 type EventMap = Record<string, (...args: any[]) => void>;
 declare class TypedEventEmitter<TEvents extends EventMap> {
@@ -277,6 +281,18 @@ export declare class ActaWsClient extends TypedEventEmitter<ActaWsClientEvents>
         active_only?: boolean;
     }): RequestId;
     logout(): void;
+    /**
+     * Redeem an invite code. Authentication is proven by the session;
+     * no additional signature is required. Validation runs client-side —
+     * invalid inputs throw `ReferralCodeError` without a round-trip.
+     */
+    redeemInvite(rawCode: string): RequestId;
+    /**
+     * Claim a vanity referral code (one-shot per taker). Validation
+     * runs client-side — invalid inputs throw `ReferralCodeError`.
+     */
+    claimReferralCode(rawCode: string): Promise<RequestId>;
+    getMyReferralInfo(): RequestId;
     getOrderStatus(orderIdHex: string): RequestId;
     cancelRfq(rfqId: string): RequestId;
     submitQuote(quote: QuoteMessage): void;
@@ -295,6 +311,27 @@ export declare class ActaWsClient extends TypedEventEmitter<ActaWsClientEvents>
         orderId: Uint8Array;
         makerSigner: SignerLike;
     }): Promise<void>;
+    /**
+     * Replace an in-flight quote on the same RFQ. Server treats this as
+     * cancel-old + place-new atomically; maker signs the NEW `order_id`.
+     */
+    submitReplaceQuote(msg: ReplaceQuoteMessage): void;
+    /** Convenience: compute new `order_id`, sign it, and send `ReplaceQuote`. */
+    submitReplaceQuoteSigned(args: {
+        oldOrderId: Uint8Array;
+        rfqId: string;
+        strike: number;
+        price: number;
+        validUntil: number;
+        nonce: number;
+        orderId: Uint8Array;
+        makerSigner: SignerLike;
+    }): Promise<void>;
+    /**
+     * Send multiple signed quotes in one WS frame. Each entry must already be
+     * a fully-built `QuoteMessage` (use `buildSignedQuoteMessage` per quote).
+     */
+    submitBatchQuotes(quotes: QuoteMessage[]): void;
     cancelQuote(rfqId: string): RequestId;
     subscribe(channels: WsChannel[], opts?: {
         underlying_mints?: string[];
@@ -311,6 +348,8 @@ export declare class ActaWsClient extends TypedEventEmitter<ActaWsClientEvents>
     }): RequestId;
     addChannels(channels: WsChannel[]): RequestId;
     removeChannels(channels: WsChannel[]): RequestId;
+    /** Query the server's view of this session's subscriptions. Response: `subscriptions` event. */
+    getSubscriptions(): RequestId;
     ping(): void;
     resumeAuth(sessionId: string): void;
     private doConnect;

package/dist/ws/client.js

@@ -1,6 +1,7 @@
 /** Acta WebSocket client (rfq-server). */
-import { buildSignedQuoteMessage, buildAcceptQuoteMessage } from "./flows";
+import { buildSignedQuoteMessage, buildSignedReplaceQuoteMessage, buildAcceptQuoteMessage, } from "./flows";
 import { assertWsU64Safe, validateQuantityBySizeRule } from "./wirePolicy";
+import { parseReferralCode, ReferralCodeError } from "./referral";
 function toGenericServerError(err) {
     const message = err instanceof Error ? err.message : String(err);
     return { type: "generic", data: { code: "client_error", message } };
@@ -403,6 +404,51 @@ export class ActaWsClient extends TypedEventEmitter {
     logout() {
         this.send({ type: "Logout" });
     }
+    // ========================================================================
+    // Referral / invite
+    // ========================================================================
+    /**
+     * Redeem an invite code. Authentication is proven by the session;
+     * no additional signature is required. Validation runs client-side —
+     * invalid inputs throw `ReferralCodeError` without a round-trip.
+     */
+    redeemInvite(rawCode) {
+        this.ensureAuthenticated();
+        const parsed = parseReferralCode(rawCode);
+        if (!parsed.ok)
+            throw new ReferralCodeError(parsed.error);
+        const requestId = this.nextRequestId();
+        this.send({
+            type: "RedeemInvite",
+            data: { request_id: requestId, code: parsed.code },
+        });
+        return requestId;
+    }
+    /**
+     * Claim a vanity referral code (one-shot per taker). Validation
+     * runs client-side — invalid inputs throw `ReferralCodeError`.
+     */
+    async claimReferralCode(rawCode) {
+        this.ensureAuthenticated();
+        const parsed = parseReferralCode(rawCode);
+        if (!parsed.ok)
+            throw new ReferralCodeError(parsed.error);
+        const requestId = this.nextRequestId();
+        this.send({
+            type: "ClaimReferralCode",
+            data: { request_id: requestId, code: parsed.code },
+        });
+        return requestId;
+    }
+    getMyReferralInfo() {
+        this.ensureAuthenticated();
+        const requestId = this.nextRequestId();
+        this.send({
+            type: "GetMyReferralInfo",
+            data: { request_id: requestId },
+        });
+        return requestId;
+    }
     getOrderStatus(orderIdHex) {
         this.ensureAuthenticated();
         const requestId = this.nextRequestId();
@@ -447,6 +493,40 @@ export class ActaWsClient extends TypedEventEmitter {
         });
         this.submitQuote(quote);
     }
+    /**
+     * Replace an in-flight quote on the same RFQ. Server treats this as
+     * cancel-old + place-new atomically; maker signs the NEW `order_id`.
+     */
+    submitReplaceQuote(msg) {
+        this.ensureAuthenticated();
+        this.send({ type: "ReplaceQuote", data: msg });
+    }
+    /** Convenience: compute new `order_id`, sign it, and send `ReplaceQuote`. */
+    async submitReplaceQuoteSigned(args) {
+        assertWsU64Safe(args.strike, "strike");
+        assertWsU64Safe(args.price, "price");
+        assertWsU64Safe(args.validUntil, "validUntil");
+        assertWsU64Safe(args.nonce, "nonce");
+        const msg = await buildSignedReplaceQuoteMessage({
+            oldOrderId: args.oldOrderId,
+            rfqId: args.rfqId,
+            strike: args.strike,
+            price: args.price,
+            validUntil: args.validUntil,
+            nonce: args.nonce,
+            orderId: args.orderId,
+            makerSigner: args.makerSigner,
+        });
+        this.submitReplaceQuote(msg);
+    }
+    /**
+     * Send multiple signed quotes in one WS frame. Each entry must already be
+     * a fully-built `QuoteMessage` (use `buildSignedQuoteMessage` per quote).
+     */
+    submitBatchQuotes(quotes) {
+        this.ensureAuthenticated();
+        this.send({ type: "BatchQuotes", data: { quotes } });
+    }
     cancelQuote(rfqId) {
         this.ensureAuthenticated();
         const requestId = this.nextRequestId();
@@ -540,6 +620,13 @@ export class ActaWsClient extends TypedEventEmitter {
         this.send({ type: "RemoveChannels", data: { request_id, channels } });
         return request_id;
     }
+    /** Query the server's view of this session's subscriptions. Response: `subscriptions` event. */
+    getSubscriptions() {
+        this.ensureAuthenticated();
+        const request_id = this.nextRequestId();
+        this.send({ type: "GetSubscriptions", data: { request_id } });
+        return request_id;
+    }
     ping() {
         if (this.ws?.readyState === WS_OPEN) {
             this.send({ type: "Ping" });
@@ -874,6 +961,18 @@ export class ActaWsClient extends TypedEventEmitter {
                     this.emit("subscriptionUpdated", d);
                 }
                 break;
+            case "RequireInvite":
+                this.emit("requireInvite");
+                break;
+            case "InviteRedeemed":
+                this.emit("inviteRedeemed", message.data);
+                break;
+            case "ReferralCodeClaimed":
+                this.emit("referralCodeClaimed", message.data);
+                break;
+            case "MyReferralInfo":
+                this.emit("myReferralInfo", message.data);
+                break;
         }
     }
     /** Taker-only: request current indicative prices for a market + position_type. */
@@ -899,7 +998,7 @@ export class ActaWsClient extends TypedEventEmitter {
         try {
             const [pubkey, signature] = await Promise.all([
                 this.authProvider.getPublicKey(),
-                this.authProvider.signChallenge(challenge),
+                this.authProvider.signMessage(challenge),
             ]);
             this.send({
                 type: "AuthChallenge",

package/dist/ws/client.test.js

@@ -51,7 +51,7 @@ function parseClientMessage(payload) {
 function makeAuthProvider(pubkey = "pubkey", signature = "signature") {
     return {
         getPublicKey: jest.fn().mockResolvedValue(pubkey),
-        signChallenge: jest.fn().mockResolvedValue(signature),
+        signMessage: jest.fn().mockResolvedValue(signature),
     };
 }
 function makeHarness(overrides = {}) {

package/dist/ws/flows.d.ts

@@ -4,7 +4,7 @@
  * - WS wire uses hex string for `order_id` and base58 for signatures
  */
 import type { Address } from "@solana/addresses";
-import type { AcceptQuoteMessage, QuoteMessage, RfqBroadcastMessage } from "./types";
+import type { AcceptQuoteMessage, QuoteMessage, ReplaceQuoteMessage, RfqBroadcastMessage } from "./types";
 import type { SignerLike } from "../chain/orders";
 export declare function buildSignedQuoteMessage(args: {
     rfqId: string;
@@ -15,6 +15,18 @@ export declare function buildSignedQuoteMessage(args: {
     orderId: Uint8Array;
     makerSigner: SignerLike;
 }): Promise<QuoteMessage>;
+export declare function buildSignedReplaceQuoteMessage(args: {
+    /** orderId of the quote being replaced (32 bytes). */
+    oldOrderId: Uint8Array;
+    rfqId: string;
+    strike: number;
+    price: number;
+    validUntil: number;
+    nonce: number;
+    /** NEW 32-byte orderId for the replacement quote. */
+    orderId: Uint8Array;
+    makerSigner: SignerLike;
+}): Promise<ReplaceQuoteMessage>;
 /**
  * Strict maker helper: build a fully-valid quote from a server RFQ broadcast.
  *

package/dist/ws/flows.js

@@ -24,6 +24,25 @@ export async function buildSignedQuoteMessage(args) {
         signature: signatureBase58,
     };
 }
+export async function buildSignedReplaceQuoteMessage(args) {
+    assertWsU64Safe(args.strike, "strike");
+    assertWsU64Safe(args.price, "price");
+    assertWsU64Safe(args.validUntil, "validUntil");
+    assertWsU64Safe(args.nonce, "nonce");
+    assertOrderId32(args.oldOrderId);
+    assertOrderId32(args.orderId);
+    const { signatureBase58 } = await signOrderIdBase58(args.makerSigner, args.orderId);
+    return {
+        old_order_id: orderIdToHex(args.oldOrderId),
+        rfq_id: args.rfqId,
+        strike: args.strike,
+        price: args.price,
+        valid_until: args.validUntil,
+        nonce: args.nonce,
+        order_id: orderIdToHex(args.orderId),
+        signature: signatureBase58,
+    };
+}
 function positionTypeToU8(positionType) {
     switch (positionType) {
         case "covered_call":

package/dist/ws/index.d.ts

@@ -6,3 +6,4 @@ export * from "./sponsoredTx";
 export * from "./apy";
 export * from "./discovery";
 export * from "./sizing";
+export * from "./referral";

package/dist/ws/index.js

@@ -6,3 +6,4 @@ export * from "./sponsoredTx";
 export * from "./apy";
 export * from "./discovery";
 export * from "./sizing";
+export * from "./referral";

package/dist/ws/referral.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Referral / invite redemption helpers.
+ *
+ * Mirrors the server-side validation defined in
+ * rust-backend/acta-types/src/invite.rs (ReferralCode::parse).
+ * Client-side validation must stay bit-identical to the server on
+ * the same input. A hardcoded fixture table is kept here and on the
+ * rust side; if either drifts, the cross-impl test will catch it.
+ */
+export declare const REFERRAL_CODE_MIN_LEN = 4;
+export declare const REFERRAL_CODE_MAX_LEN = 16;
+declare const brand: unique symbol;
+/**
+ * A normalized, validated referral code. The only way to obtain one
+ * is through `parseReferralCode`, which enforces trim + ASCII
+ * uppercase and length/charset bounds identical to the server's
+ * `ReferralCode::parse`.
+ */
+export type ReferralCode = string & {
+    readonly [brand]: "ReferralCode";
+};
+export type ReferralCodeFormatError = {
+    kind: "length";
+    min: number;
+    max: number;
+} | {
+    kind: "charset";
+};
+export declare class ReferralCodeError extends Error {
+    readonly detail: ReferralCodeFormatError;
+    constructor(detail: ReferralCodeFormatError);
+}
+/**
+ * Trim + ASCII uppercase. No length or charset check. Useful for
+ * showing a live preview as the user types.
+ */
+export declare function normalizeReferralCode(input: string): string;
+/**
+ * Parse + validate + normalize a user-supplied referral code.
+ * Mirrors `ReferralCode::parse` on the server. A successful result
+ * carries the canonical branded `ReferralCode`.
+ */
+export declare function parseReferralCode(input: string): {
+    ok: true;
+    code: ReferralCode;
+} | {
+    ok: false;
+    error: ReferralCodeFormatError;
+};
+export type InviteErrorReason = "invalid_code" | "code_exhausted" | "code_expired" | "code_owner_inactive" | "code_owner_blacklisted" | "already_registered" | "internal_error";
+export type ClaimErrorReason = "not_registered" | "invalid_format" | "code_taken" | "reserved" | "internal_error";
+export type TakerStatus = "pending" | "active";
+export {};

package/dist/ws/referral.js

@@ -0,0 +1,51 @@
+/**
+ * Referral / invite redemption helpers.
+ *
+ * Mirrors the server-side validation defined in
+ * rust-backend/acta-types/src/invite.rs (ReferralCode::parse).
+ * Client-side validation must stay bit-identical to the server on
+ * the same input. A hardcoded fixture table is kept here and on the
+ * rust side; if either drifts, the cross-impl test will catch it.
+ */
+export const REFERRAL_CODE_MIN_LEN = 4;
+export const REFERRAL_CODE_MAX_LEN = 16;
+export class ReferralCodeError extends Error {
+    detail;
+    constructor(detail) {
+        super(detail.kind === "length"
+            ? `code length must be between ${detail.min} and ${detail.max}`
+            : "code must contain only ASCII letters and digits");
+        this.detail = detail;
+        this.name = "ReferralCodeError";
+    }
+}
+/**
+ * Trim + ASCII uppercase. No length or charset check. Useful for
+ * showing a live preview as the user types.
+ */
+export function normalizeReferralCode(input) {
+    return input.trim().toUpperCase();
+}
+/**
+ * Parse + validate + normalize a user-supplied referral code.
+ * Mirrors `ReferralCode::parse` on the server. A successful result
+ * carries the canonical branded `ReferralCode`.
+ */
+export function parseReferralCode(input) {
+    const normalized = normalizeReferralCode(input);
+    if (normalized.length < REFERRAL_CODE_MIN_LEN ||
+        normalized.length > REFERRAL_CODE_MAX_LEN) {
+        return {
+            ok: false,
+            error: {
+                kind: "length",
+                min: REFERRAL_CODE_MIN_LEN,
+                max: REFERRAL_CODE_MAX_LEN,
+            },
+        };
+    }
+    if (!/^[A-Z0-9]+$/.test(normalized)) {
+        return { ok: false, error: { kind: "charset" } };
+    }
+    return { ok: true, code: normalized };
+}

package/dist/ws/referral.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ws/referral.test.js

@@ -0,0 +1,53 @@
+import { normalizeReferralCode, parseReferralCode } from "./referral";
+// =============================================================================
+// Cross-impl fixture.
+//
+// Bit-for-bit identical to the fixture in
+//   rust-backend/acta-types/src/invite.rs::tests
+// If either side changes, update both.
+// =============================================================================
+const ACCEPT_FIXTURES = [
+    ["NIKITA", "NIKITA"],
+    ["nikita", "NIKITA"],
+    ["  abc1 ", "ABC1"],
+    ["ABCD", "ABCD"],
+    ["1234567890ABCDEF", "1234567890ABCDEF"],
+];
+describe("parseReferralCode", () => {
+    test.each(ACCEPT_FIXTURES)("accepts %j → %j", (input, expected) => {
+        const res = parseReferralCode(input);
+        expect(res.ok).toBe(true);
+        if (res.ok)
+            expect(res.code).toBe(expected);
+    });
+    test("rejects too short", () => {
+        const res = parseReferralCode("abc");
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.kind).toBe("length");
+    });
+    test("rejects too long", () => {
+        const res = parseReferralCode("A".repeat(17));
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.kind).toBe("length");
+    });
+    test("rejects non-ascii", () => {
+        const res = parseReferralCode("абвгд");
+        expect(res.ok).toBe(false);
+        // Cyrillic passes length but fails charset.
+        if (!res.ok)
+            expect(res.error.kind).toBe("charset");
+    });
+    test("rejects punctuation", () => {
+        const res = parseReferralCode("ABC-12");
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.kind).toBe("charset");
+    });
+});
+describe("normalizeReferralCode", () => {
+    test("trims and uppercases", () => {
+        expect(normalizeReferralCode("  nikita ")).toBe("NIKITA");
+    });
+});