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

package/dist/cjs/ws/auth.js

@@ -7,6 +7,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
@@ -52,9 +55,9 @@ class KeypairAuthProvider {
     async getPublicKey() {
         return this.address;
     }
-    async signChallenge(challenge) {
-        const challengeBytes = utf8ToBytes(challenge);
-        const signatureBytes = await (0, keys_1.signBytes)(this.privateKey, challengeBytes);
+    async signMessage(message) {
+        const messageBytes = utf8ToBytes(message);
+        const signatureBytes = await (0, keys_1.signBytes)(this.privateKey, messageBytes);
         return bytesToBase58(signatureBytes);
     }
 }
@@ -76,10 +79,10 @@ 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);
     }
 }
@@ -89,16 +92,16 @@ exports.WalletAuthProvider = WalletAuthProvider;
  */
 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);
     }
 }
 exports.CustomAuthProvider = CustomAuthProvider;

package/dist/cjs/ws/client.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ActaWsClient = void 0;
 const flows_1 = require("./flows");
 const wirePolicy_1 = require("./wirePolicy");
+const referral_1 = require("./referral");
 function toGenericServerError(err) {
     const message = err instanceof Error ? err.message : String(err);
     return { type: "generic", data: { code: "client_error", message } };
@@ -406,6 +407,51 @@ 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 = (0, referral_1.parseReferralCode)(rawCode);
+        if (!parsed.ok)
+            throw new referral_1.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 = (0, referral_1.parseReferralCode)(rawCode);
+        if (!parsed.ok)
+            throw new referral_1.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();
@@ -877,6 +923,18 @@ 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. */
@@ -902,7 +960,7 @@ 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/cjs/ws/client.test.js

@@ -53,7 +53,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/cjs/ws/index.js

@@ -22,3 +22,4 @@ __exportStar(require("./sponsoredTx"), exports);
 __exportStar(require("./apy"), exports);
 __exportStar(require("./discovery"), exports);
 __exportStar(require("./sizing"), exports);
+__exportStar(require("./referral"), exports);

package/dist/cjs/ws/referral.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReferralCodeError = exports.REFERRAL_CODE_MAX_LEN = exports.REFERRAL_CODE_MIN_LEN = void 0;
+exports.normalizeReferralCode = normalizeReferralCode;
+exports.parseReferralCode = parseReferralCode;
+exports.REFERRAL_CODE_MIN_LEN = 4;
+exports.REFERRAL_CODE_MAX_LEN = 16;
+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";
+    }
+}
+exports.ReferralCodeError = ReferralCodeError;
+/**
+ * Trim + ASCII uppercase. No length or charset check. Useful for
+ * showing a live preview as the user types.
+ */
+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`.
+ */
+function parseReferralCode(input) {
+    const normalized = normalizeReferralCode(input);
+    if (normalized.length < exports.REFERRAL_CODE_MIN_LEN ||
+        normalized.length > exports.REFERRAL_CODE_MAX_LEN) {
+        return {
+            ok: false,
+            error: {
+                kind: "length",
+                min: exports.REFERRAL_CODE_MIN_LEN,
+                max: exports.REFERRAL_CODE_MAX_LEN,
+            },
+        };
+    }
+    if (!/^[A-Z0-9]+$/.test(normalized)) {
+        return { ok: false, error: { kind: "charset" } };
+    }
+    return { ok: true, code: normalized };
+}

package/dist/cjs/ws/referral.test.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const referral_1 = require("./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 = (0, referral_1.parseReferralCode)(input);
+        expect(res.ok).toBe(true);
+        if (res.ok)
+            expect(res.code).toBe(expected);
+    });
+    test("rejects too short", () => {
+        const res = (0, referral_1.parseReferralCode)("abc");
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.kind).toBe("length");
+    });
+    test("rejects too long", () => {
+        const res = (0, referral_1.parseReferralCode)("A".repeat(17));
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.kind).toBe("length");
+    });
+    test("rejects non-ascii", () => {
+        const res = (0, referral_1.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 = (0, referral_1.parseReferralCode)("ABC-12");
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.kind).toBe("charset");
+    });
+});
+describe("normalizeReferralCode", () => {
+    test("trims and uppercases", () => {
+        expect((0, referral_1.normalizeReferralCode)("  nikita ")).toBe("NIKITA");
+    });
+});

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, 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;

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 } };
@@ -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();
@@ -874,6 +920,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 +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",

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

package/dist/ws/types.d.ts

@@ -1,4 +1,5 @@
 import type { Address } from "@solana/addresses";
+import type { ClaimErrorReason, InviteErrorReason, TakerStatus } from "./referral";
 export type UuidString = string;
 export type RequestId = string;
 export type PubkeyBase58 = string;
@@ -208,6 +209,40 @@ export type ClientMessage = {
         request_id: RequestId;
         channels: WsChannel[];
     };
+} | {
+    type: "RedeemInvite";
+    data: {
+        request_id: RequestId;
+        code: string;
+    };
+} | {
+    type: "ClaimReferralCode";
+    data: {
+        request_id: RequestId;
+        code: string;
+    };
+} | {
+    type: "GetMyReferralInfo";
+    data: {
+        request_id: RequestId;
+    };
+};
+export type InviteRedeemedData = {
+    request_id: RequestId;
+    referral_code: string;
+};
+export type ReferralCodeClaimedData = {
+    request_id: RequestId;
+    referral_code: string;
+};
+export type MyReferralInfoData = {
+    request_id: RequestId;
+    referral_code: string;
+    status: TakerStatus;
+    total_invited: number;
+    invited_this_period: number;
+    max_invites_per_period: number;
+    next_slot_frees_in_seconds: number;
 };
 export type GetMarketDescriptorsMessage = {
     request_id: RequestId;
@@ -538,6 +573,17 @@ export type ServerMessage = {
         underlying_mints?: string[];
         quote_mints?: string[];
     };
+} | {
+    type: "RequireInvite";
+} | {
+    type: "InviteRedeemed";
+    data: InviteRedeemedData;
+} | {
+    type: "ReferralCodeClaimed";
+    data: ReferralCodeClaimedData;
+} | {
+    type: "MyReferralInfo";
+    data: MyReferralInfoData;
 };
 export type MarketDescriptorInfo = {
     market: MarketDescriptor;
@@ -577,128 +623,154 @@ export type QuoteRefreshRequestedMessage = {
     reason: QuoteRefreshReason;
 };
 export type ServerError = {
-    type: "unauthenticated";
+    type: "Unauthenticated";
     data: {
         action: AuthRequiredAction;
     };
 } | {
-    type: "unauthorized";
+    type: "Unauthorized";
     data: {
         role: UserRole;
         action: AuthRequiredAction;
     };
 } | {
-    type: "rfq_not_found";
+    type: "RfqNotFound";
 } | {
-    type: "rfq_not_active";
+    type: "RfqNotActive";
 } | {
-    type: "invalid_state";
+    type: "RfqAlreadyLocked";
+} | {
+    type: "InvalidState";
     data: {
         state: RfqStateError;
     };
 } | {
-    type: "quote_locked";
+    type: "QuoteLocked";
     data: {
         reason: QuoteLockedReason;
     };
 } | {
-    type: "quote_not_found";
+    type: "QuoteNotFound";
 } | {
-    type: "quote_expired";
+    type: "QuoteExpired";
 } | {
-    type: "invalid_strike";
+    type: "QuoteExpiryTooShort";
+    data: {
+        min_seconds: WsU32;
+    };
 } | {
-    type: "invalid_valid_until";
+    type: "InvalidStrike";
 } | {
-    type: "order_id_mismatch";
+    type: "InvalidValidUntil";
 } | {
-    type: "signature_timeout";
+    type: "OrderIdMismatch";
 } | {
-    type: "oracle_not_ready";
+    type: "UnknownOrder";
 } | {
-    type: "oracle_price_stale";
+    type: "SignatureTimeout";
+} | {
+    type: "OracleNotReady";
+} | {
+    type: "OraclePriceStale";
     data: {
         age_seconds: WsU64;
     };
 } | {
-    type: "oracle_price_not_ready";
+    type: "OraclePriceNotReady";
 } | {
-    type: "invalid_position_type";
+    type: "InvalidPositionType";
 } | {
-    type: "invalid_market";
+    type: "InvalidMarket";
     data: {
         pubkey: string;
     };
 } | {
-    type: "market_metadata_incomplete";
+    type: "MarketMetadataIncomplete";
     data: {
         details: string;
     };
 } | {
-    type: "token_metadata_incomplete";
+    type: "TokenMetadataIncomplete";
     data: {
         details: string;
     };
 } | {
-    type: "rate_limit";
+    type: "RateLimit";
     data: RateLimitReason;
 } | {
-    type: "token_oi_cap_exceeded";
+    type: "Cap";
+    data: CapErrorData;
+} | {
+    type: "InternalError";
+} | {
+    type: "KernelNotAvailable";
+} | {
+    type: "DbDisabled";
     data: {
+        feature: DbFeature;
+    };
+} | {
+    type: "ServerShuttingDown";
+} | {
+    type: "Generic";
+    data: {
+        code: ErrorCode;
+        message: ErrorMessage;
+    };
+} | {
+    type: "InviteRequired";
+} | {
+    type: "Invite";
+    data: InviteErrorReason;
+} | {
+    type: "Claim";
+    data: ClaimErrorReason;
+} | {
+    type: "generic";
+    data: {
+        code: ErrorCode;
+        message: ErrorMessage;
+    };
+};
+/**
+ * Externally-tagged union for rust's `CapError`. Only one key is
+ * present at a time. Lock-step with
+ * `rust-backend/acta-types/src/errors.rs::CapError`.
+ */
+export type CapErrorData = {
+    token_oi_cap_exceeded: {
         underlying_mint: string;
         current: WsU64;
         limit: WsU64;
     };
 } | {
-    type: "market_oi_cap_exceeded";
-    data: {
+    market_oi_cap_exceeded: {
         market_id: string;
         current: WsU64;
         limit: WsU64;
     };
 } | {
-    type: "maker_position_cap_exceeded";
-    data: {
+    maker_position_cap_exceeded: {
         current: WsU32;
         limit: WsU32;
     };
 } | {
-    type: "maker_notional_cap_exceeded";
-    data: {
+    maker_notional_cap_exceeded: {
         underlying_mint: string;
         current: WsU64;
         limit: WsU64;
     };
 } | {
-    type: "maker_insufficient_balance";
-    data: {
+    maker_insufficient_balance: {
         available: WsU64;
         required: WsU64;
     };
 } | {
-    type: "quote_notional_cap_exceeded";
-    data: {
+    quote_notional_cap_exceeded: {
         quote_mint: string;
         current: WsU64;
         limit: WsU64;
     };
-} | {
-    type: "internal_error";
-} | {
-    type: "kernel_not_available";
-} | {
-    type: "db_disabled";
-    data: {
-        feature: DbFeature;
-    };
-} | {
-    type: "server_shutting_down";
-} | {
-    type: "generic";
-    data: {
-        code: ErrorCode;
-        message: ErrorMessage;
-    };
 };
 /** Confirms quote was received and validated. */
 export type QuoteAcknowledgedMessage = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acta-markets/ts-sdk",
-  "version": "0.0.21-beta",
+  "version": "0.0.22-beta",
   "description": "TypeScript SDK for Acta Protocol",
   "type": "module",
   "main": "dist/index.js",