@acta-markets/ts-sdk 0.0.20-beta → 0.0.22-beta

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, 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, 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";
@@ -88,6 +88,12 @@ export type ActaWsClientEvents = {
     earnSummary: (data: EarnSummaryData) => void;
     tokenMarketsInfo: (data: TokenMarketsInfoData) => void;
     subscriptions: (msg: SubscriptionsMessage) => void;
+    subscriptionUpdated: (data: {
+        request_id: RequestId;
+        channels: WsChannel[];
+        underlying_mints?: string[];
+        quote_mints?: string[];
+    }) => void;
     activeRfqs: (rfqs: ActiveRfqInfo[]) => void;
     rfqBroadcast: (rfq: RfqBroadcastMessage) => void;
     rfqSkipped: (msg: RfqSkippedMessage) => void;
@@ -106,6 +112,12 @@ export type ActaWsClientEvents = {
     quoteExpired: (msg: QuoteExpiredMessage) => void;
     indicativePrices: (msg: IndicativePricesMessage) => void;
     indicativePricesRequest: (msg: IndicativePricesRequestMessage) => void;
+    makerBalances: (msg: MakerBalancesMessage) => void;
+    makerPositions: (msg: MakerPositionsMessage) => void;
+    myTrades: (msg: MyTradesMessage) => void;
+    myCaps: (msg: MyCapsMessage) => void;
+    makerMarkets: (msg: MakerMarketsMessage) => void;
+    myQuotes: (msg: MyQuotesMessage) => void;
     myActiveRfqs: (msg: MyActiveRfqsMessage) => void;
     orderStatus: (msg: OrderStatusMessage) => void;
     orderAccepted: (orderId: string) => void;
@@ -133,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> {
@@ -176,8 +192,8 @@ export declare class ActaWsClient extends TypedEventEmitter<ActaWsClientEvents>
     private pingTimer;
     private shouldReconnect;
     private subscribedChannels;
-    private subscribedMarkets;
-    private hasMarketScope;
+    private underlyingMintScope;
+    private quoteMintScope;
     private marketDescriptorsByMarket;
     readonly state: ClientState;
     constructor(options: ActaWsClientOptions);
@@ -233,7 +249,50 @@ export declare class ActaWsClient extends TypedEventEmitter<ActaWsClientEvents>
     }): RequestId;
     getEarnSummary(): RequestId;
     getTokenMarketsInfo(underlyingMint: string): RequestId;
+    /** Maker-only: get balances per deposited token (total, locked, available). */
+    getMakerBalances(): RequestId;
+    /** Maker-only: get open positions with optional filters. */
+    getMakerPositions(args?: {
+        market?: string;
+        underlying_mint?: string;
+        status?: string[];
+        min_expiry_ts?: number;
+    }): RequestId;
+    /** Maker-only: get trade history with keyset pagination. */
+    getMyTrades(args?: {
+        limit?: number;
+        cursor?: number;
+        cursor_id?: string;
+        market?: string;
+    }): RequestId;
+    /** Maker-only: get position, notional, and balance caps. */
+    getMyCaps(): RequestId;
+    /** Maker-only: get markets where maker has deposits, with optional filters and stats. */
+    getMarketsForMaker(args?: {
+        underlying_mints?: string[];
+        quote_mints?: string[];
+        min_expiry_ts?: number;
+        max_expiry_ts?: number;
+        is_put?: boolean;
+        include_stats?: boolean;
+    }): RequestId;
+    /** Maker-only: get submitted quotes with status. */
+    getMyQuotes(args?: {
+        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;
@@ -253,8 +312,21 @@ export declare class ActaWsClient extends TypedEventEmitter<ActaWsClientEvents>
         makerSigner: SignerLike;
     }): Promise<void>;
     cancelQuote(rfqId: string): RequestId;
-    subscribe(channels: WsChannel[], markets?: string[]): RequestId;
+    subscribe(channels: WsChannel[], opts?: {
+        underlying_mints?: string[];
+        quote_mints?: string[];
+    }): RequestId;
     unsubscribe(channels: WsChannel[]): RequestId;
+    addMints(opts: {
+        underlying_mints?: string[];
+        quote_mints?: string[];
+    }): RequestId;
+    removeMints(opts: {
+        underlying_mints?: string[];
+        quote_mints?: string[];
+    }): RequestId;
+    addChannels(channels: WsChannel[]): RequestId;
+    removeChannels(channels: WsChannel[]): 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 { 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 } };
@@ -107,8 +108,8 @@ export class ActaWsClient extends TypedEventEmitter {
     pingTimer = null;
     shouldReconnect = true;
     subscribedChannels = new Set(["rfqs"]);
-    subscribedMarkets = new Set();
-    hasMarketScope = false;
+    underlyingMintScope = null; // null = all
+    quoteMintScope = null; // null = all
     marketDescriptorsByMarket = new Map();
     state = {
         stats: null,
@@ -336,9 +337,118 @@ export class ActaWsClient extends TypedEventEmitter {
         });
         return requestId;
     }
+    /** Maker-only: get balances per deposited token (total, locked, available). */
+    getMakerBalances() {
+        this.ensureAuthenticated();
+        const requestId = this.nextRequestId();
+        this.send({
+            type: "GetMakerBalances",
+            data: { request_id: requestId },
+        });
+        return requestId;
+    }
+    /** Maker-only: get open positions with optional filters. */
+    getMakerPositions(args) {
+        this.ensureAuthenticated();
+        const requestId = this.nextRequestId();
+        const data = {
+            request_id: requestId,
+            ...args,
+        };
+        this.send({ type: "GetMakerPositions", data });
+        return requestId;
+    }
+    /** Maker-only: get trade history with keyset pagination. */
+    getMyTrades(args) {
+        this.ensureAuthenticated();
+        const requestId = this.nextRequestId();
+        const data = {
+            request_id: requestId,
+            ...args,
+        };
+        this.send({ type: "GetMyTrades", data });
+        return requestId;
+    }
+    /** Maker-only: get position, notional, and balance caps. */
+    getMyCaps() {
+        this.ensureAuthenticated();
+        const requestId = this.nextRequestId();
+        this.send({
+            type: "GetMyCaps",
+            data: { request_id: requestId },
+        });
+        return requestId;
+    }
+    /** Maker-only: get markets where maker has deposits, with optional filters and stats. */
+    getMarketsForMaker(args) {
+        this.ensureAuthenticated();
+        const requestId = this.nextRequestId();
+        const data = {
+            request_id: requestId,
+            ...args,
+        };
+        this.send({ type: "GetMarketsForMaker", data });
+        return requestId;
+    }
+    /** Maker-only: get submitted quotes with status. */
+    getMyQuotes(args) {
+        this.ensureAuthenticated();
+        const requestId = this.nextRequestId();
+        const data = {
+            request_id: requestId,
+            active_only: args?.active_only ?? true,
+        };
+        this.send({ type: "GetMyQuotes", data });
+        return requestId;
+    }
     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();
@@ -392,21 +502,25 @@ export class ActaWsClient extends TypedEventEmitter {
         });
         return requestId;
     }
-    subscribe(channels, markets) {
+    subscribe(channels, opts) {
         this.ensureAuthenticated();
         const request_id = this.nextRequestId();
         for (const c of channels)
             this.subscribedChannels.add(c);
-        if (markets) {
-            this.hasMarketScope = true;
-            this.subscribedMarkets = new Set(markets);
+        if (opts?.underlying_mints) {
+            this.underlyingMintScope = new Set(opts.underlying_mints);
         }
-        this.send({
-            type: "Subscribe",
-            data: this.hasMarketScope
-                ? { request_id, channels, markets: Array.from(this.subscribedMarkets) }
-                : { request_id, channels },
-        });
+        if (opts?.quote_mints) {
+            this.quoteMintScope = new Set(opts.quote_mints);
+        }
+        const data = { request_id, channels };
+        if (this.underlyingMintScope) {
+            data.underlying_mints = Array.from(this.underlyingMintScope);
+        }
+        if (this.quoteMintScope) {
+            data.quote_mints = Array.from(this.quoteMintScope);
+        }
+        this.send({ type: "Subscribe", data });
         return request_id;
     }
     unsubscribe(channels) {
@@ -420,6 +534,58 @@ export class ActaWsClient extends TypedEventEmitter {
         });
         return request_id;
     }
+    addMints(opts) {
+        this.ensureAuthenticated();
+        const request_id = this.nextRequestId();
+        if (opts.underlying_mints) {
+            if (!this.underlyingMintScope)
+                this.underlyingMintScope = new Set();
+            for (const m of opts.underlying_mints)
+                this.underlyingMintScope.add(m);
+        }
+        if (opts.quote_mints) {
+            if (!this.quoteMintScope)
+                this.quoteMintScope = new Set();
+            for (const m of opts.quote_mints)
+                this.quoteMintScope.add(m);
+        }
+        this.send({ type: "AddMints", data: { request_id, ...opts } });
+        return request_id;
+    }
+    removeMints(opts) {
+        this.ensureAuthenticated();
+        const request_id = this.nextRequestId();
+        if (opts.underlying_mints && this.underlyingMintScope) {
+            for (const m of opts.underlying_mints)
+                this.underlyingMintScope.delete(m);
+            if (this.underlyingMintScope.size === 0)
+                this.underlyingMintScope = null;
+        }
+        if (opts.quote_mints && this.quoteMintScope) {
+            for (const m of opts.quote_mints)
+                this.quoteMintScope.delete(m);
+            if (this.quoteMintScope.size === 0)
+                this.quoteMintScope = null;
+        }
+        this.send({ type: "RemoveMints", data: { request_id, ...opts } });
+        return request_id;
+    }
+    addChannels(channels) {
+        this.ensureAuthenticated();
+        const request_id = this.nextRequestId();
+        for (const c of channels)
+            this.subscribedChannels.add(c);
+        this.send({ type: "AddChannels", data: { request_id, channels } });
+        return request_id;
+    }
+    removeChannels(channels) {
+        this.ensureAuthenticated();
+        const request_id = this.nextRequestId();
+        for (const c of channels)
+            this.subscribedChannels.delete(c);
+        this.send({ type: "RemoveChannels", data: { request_id, channels } });
+        return request_id;
+    }
     ping() {
         if (this.ws?.readyState === WS_OPEN) {
             this.send({ type: "Ping" });
@@ -570,6 +736,21 @@ export class ActaWsClient extends TypedEventEmitter {
             case "MyCaps":
                 this.emit("myCaps", message.data);
                 break;
+            case "MakerBalances":
+                this.emit("makerBalances", message.data);
+                break;
+            case "MakerPositions":
+                this.emit("makerPositions", message.data);
+                break;
+            case "MyTrades":
+                this.emit("myTrades", message.data);
+                break;
+            case "MakerMarkets":
+                this.emit("makerMarkets", message.data);
+                break;
+            case "MyQuotes":
+                this.emit("myQuotes", message.data);
+                break;
             case "MyActiveRfqs":
                 this.handleMyActiveRfqs(message.data);
                 break;
@@ -727,6 +908,30 @@ export class ActaWsClient extends TypedEventEmitter {
             case "UnsubscribeAck":
                 this.emit("unsubscribeAck", message.data);
                 break;
+            case "SubscriptionUpdated":
+                {
+                    const d = message.data;
+                    // Sync local state from the server's authoritative response.
+                    this.subscribedChannels = new Set(d.channels);
+                    this.underlyingMintScope =
+                        d.underlying_mints != null ? new Set(d.underlying_mints) : null;
+                    this.quoteMintScope =
+                        d.quote_mints != null ? new Set(d.quote_mints) : null;
+                    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. */
@@ -752,7 +957,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",
@@ -812,9 +1017,13 @@ export class ActaWsClient extends TypedEventEmitter {
         if (this.subscribedChannels.size > 0) {
             const channels = Array.from(this.subscribedChannels);
             const request_id = this.nextRequestId();
-            const data = this.hasMarketScope
-                ? { request_id, channels, markets: Array.from(this.subscribedMarkets) }
-                : { request_id, channels };
+            const data = { request_id, channels };
+            if (this.underlyingMintScope) {
+                data.underlying_mints = Array.from(this.underlyingMintScope);
+            }
+            if (this.quoteMintScope) {
+                data.quote_mints = Array.from(this.quoteMintScope);
+            }
             this.send({ type: "Subscribe", data });
         }
     }

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/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");
+    });
+});