@magield/node 0.7.1 → 0.8.2

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { Decision } from '@magield/proto';
 import { type BreakerOptions } from './breaker.js';
 import type { DecisionName, EvaluateInput, FeedbackInput, LimitCheckInput, LimitVerdict, TrustDeviceInput, TrustedDevice, Verdict } from './types.js';
+import { type BonusRequest, type MoneyVerdict, type PaymentRequest } from './igaming.js';
 /**
  * The backend client.
  *
@@ -75,6 +76,19 @@ export declare class ShieldClient {
      * same on the good path and the bad one.
      */
     evaluate(input: EvaluateInput): Promise<Verdict>;
+    /**
+     * A deposit, and what to do with it: take it, ask for 3-D Secure, or
+     * decline. A deposit under review is taken; the case is decided before any
+     * of it can leave. Never throws, like `evaluate`.
+     */
+    deposit(request: PaymentRequest): Promise<MoneyVerdict>;
+    /**
+     * A withdrawal, and what to do with it. `handling === 'hold'` means keep it
+     * pending until the case webhook approves or rejects it.
+     */
+    withdraw(request: PaymentRequest): Promise<MoneyVerdict>;
+    /** A bonus, promo or referral claim, and whether to credit it now, later or never. */
+    bonusClaim(request: BonusRequest): Promise<MoneyVerdict>;
     /**
      * Reports what happened after a decision.
      *

package/dist/client.js

@@ -3,6 +3,7 @@ import { credentials, Metadata, status } from '@grpc/grpc-js';
 import { CheckMode, CheckRequest, Decision, DevicesClient, EvaluateRequest, EvaluationClient, FeedbackRequest, LimitsClient, TrustRequest, TrustState, } from '@magield/proto';
 import { Breaker } from './breaker.js';
 import { decisionName, modeName, outcomeValue } from './decisions.js';
+import { evaluateMoney } from './igaming.js';
 /**
  * The backend client.
  *
@@ -71,6 +72,25 @@ export class ShieldClient {
             return this.#failOpen(err);
         }
     }
+    /**
+     * A deposit, and what to do with it: take it, ask for 3-D Secure, or
+     * decline. A deposit under review is taken; the case is decided before any
+     * of it can leave. Never throws, like `evaluate`.
+     */
+    deposit(request) {
+        return evaluateMoney(this, 'deposit', request, this.#config.onError);
+    }
+    /**
+     * A withdrawal, and what to do with it. `handling === 'hold'` means keep it
+     * pending until the case webhook approves or rejects it.
+     */
+    withdraw(request) {
+        return evaluateMoney(this, 'withdraw', request, this.#config.onError);
+    }
+    /** A bonus, promo or referral claim, and whether to credit it now, later or never. */
+    bonusClaim(request) {
+        return evaluateMoney(this, 'bonus_claim', request, this.#config.onError);
+    }
     /**
      * Reports what happened after a decision.
      *
@@ -209,6 +229,7 @@ export class ShieldClient {
             token: Buffer.from(input.token ?? '', 'utf8'),
             context: { ...(input.context ?? {}) },
             ...(input.keys === undefined ? {} : { keys: identifiers(input.keys) }),
+            ...(input.attributes === undefined ? {} : { attributes: transactionAttributes(input.attributes) }),
             ...(input.network === undefined && input.ip === undefined
                 ? {}
                 : { network: networkContext({ ip: input.ip, ...input.network }) }),
@@ -363,9 +384,35 @@ function identifiers(keys) {
         sessionId: keys.sessionId ?? '',
         apiKeyId: keys.apiKeyId ?? '',
         passwordSha1Prefix: keys.passwordSha1Prefix ?? '',
+        paymentMethod: keys.paymentMethod ?? '',
+        paymentBin: keys.paymentBin ?? '',
+        promoCode: keys.promoCode ?? '',
+        affiliateId: keys.affiliateId ?? '',
+        documentHash: keys.documentHash ?? '',
+        addressHash: keys.addressHash ?? '',
+        referrerId: keys.referrerId ?? '',
         custom: { ...(keys.custom ?? {}) },
     };
 }
+/** Unset numbers and flags stay unset on the wire, so the gateway can tell "not sent" from zero. */
+function transactionAttributes(attributes) {
+    return {
+        ...(attributes.amount === undefined ? {} : { amount: attributes.amount }),
+        currency: attributes.currency ?? '',
+        paymentType: attributes.paymentType ?? '',
+        paymentCountry: attributes.paymentCountry ?? '',
+        bonusType: attributes.bonusType ?? '',
+        gameCategory: attributes.gameCategory ?? '',
+        ...(attributes.stake === undefined ? {} : { stake: attributes.stake }),
+        ...(attributes.odds === undefined ? {} : { odds: attributes.odds }),
+        kycStatus: attributes.kycStatus ?? '',
+        ...(attributes.selfExcluded === undefined ? {} : { selfExcluded: attributes.selfExcluded }),
+        ...(attributes.depositLimitReached === undefined ? {} : { depositLimitReached: attributes.depositLimitReached }),
+        changed: attributes.changed ?? '',
+        ...(attributes.age === undefined ? {} : { age: Math.floor(attributes.age) }),
+        custom: { ...(attributes.custom ?? {}) },
+    };
+}
 function networkContext(network) {
     return {
         ip: network.ip ?? '',

package/dist/decisions.js

@@ -18,6 +18,7 @@ import { Decision, Mode, Outcome } from '@magield/proto';
 const DECISIONS = new Map([
     [Decision.DECISION_ALLOW, 'allow'],
     [Decision.DECISION_ALLOW_FLAGGED, 'allow_flagged'],
+    [Decision.DECISION_REVIEW, 'review'],
     [Decision.DECISION_CHALLENGE, 'challenge'],
     [Decision.DECISION_STEP_UP, 'step_up'],
     [Decision.DECISION_THROTTLE, 'throttle'],

package/dist/igaming.d.ts

@@ -0,0 +1,138 @@
+import type { DecisionName, EvaluateInput, Identifiers, NetworkContext, TransactionAttributes, Verdict } from './types.js';
+/**
+ * The money actions, typed: deposit, withdraw and bonus claim, each turned into
+ * what to do next.
+ *
+ * A verdict says what the engine decided; an operator's cashier needs to know
+ * whether to take the money, hold it, ask for more, or refuse. That mapping is
+ * different per action — `review` on a withdrawal means "keep it pending until
+ * an analyst decides", on a deposit it means "take it, and look before any of
+ * it leaves" — and getting it wrong is how a held withdrawal gets paid out
+ * anyway. So the mapping lives here, once, and the helpers return it beside
+ * the verdict.
+ */
+/**
+ * What to do with the transaction.
+ *
+ * - `proceed`: go ahead.
+ * - `hold`: keep it pending. Release it on a `case.approved` webhook, cancel
+ *   it on `case.rejected` (see `verifyCaseWebhook`).
+ * - `challenge`: show `verdict.challenge` and retry with the solution.
+ * - `step_up`: ask for more proof — 3-D Secure on a deposit, a second factor
+ *   on a withdrawal or a bonus.
+ * - `retry_later`: after `verdict.retryAfterMs`.
+ * - `refuse`: decline it. Say no more than your terms require.
+ */
+export type Handling = 'proceed' | 'hold' | 'challenge' | 'step_up' | 'retry_later' | 'refuse';
+export type MoneyAction = 'deposit' | 'withdraw' | 'bonus_claim';
+/** The recommended handling of a decision on a money action. */
+export declare function handlingFor(action: MoneyAction, decision: DecisionName): Handling;
+export interface MoneyVerdict {
+    readonly verdict: Verdict;
+    readonly handling: Handling;
+    /** One sentence, for logs and for whoever reads them at 3am. */
+    readonly advice: string;
+}
+interface MoneyRequestBase {
+    /** The account: whatever you send as `username` everywhere else. */
+    readonly account: string;
+    /**
+     * Your own id for this transaction. Sent as `requestId`, so a chargeback or
+     * an analyst's decision weeks later is reported against the id you already
+     * keep — no evaluation id needs storing — and the case webhook names it.
+     */
+    readonly transactionId: string;
+    /** The web SDK's token from the cashier page. */
+    readonly token?: string;
+    readonly ip?: string;
+    readonly network?: NetworkContext;
+    readonly sessionId?: string;
+    /** Any other identifiers: email, phone, user id, document or address hash. */
+    readonly keys?: Identifiers;
+    /** Anything else about the transaction: KYC status, deposit limit reached, age… */
+    readonly attributes?: TransactionAttributes;
+    readonly context?: Readonly<Record<string, string>>;
+}
+export interface PaymentRequest extends MoneyRequestBase {
+    /** In your base currency. */
+    readonly amount: number;
+    readonly currency?: string;
+    /** The PSP's card fingerprint or token, or the wallet id — never the card number. */
+    readonly paymentMethod?: string;
+    readonly paymentBin?: string;
+    readonly paymentType?: TransactionAttributes['paymentType'];
+    readonly paymentCountry?: string;
+}
+export interface BonusRequest extends MoneyRequestBase {
+    readonly bonusType: 'welcome' | 'reload' | 'free_spins' | 'cashback' | 'referral' | (string & {});
+    /** What the bonus is worth, in your base currency, for the report's "bonus cost prevented". */
+    readonly value?: number;
+    readonly promoCode?: string;
+    /** The referring account, for referral rewards. */
+    readonly referrerId?: string;
+    readonly affiliateId?: string;
+}
+/** What the helpers need of the client: `evaluate`, and somewhere to say what was dropped. */
+export interface Evaluator {
+    evaluate(input: EvaluateInput): Promise<Verdict>;
+}
+export declare function evaluateMoney(shield: Evaluator, action: MoneyAction, request: PaymentRequest | BonusRequest, onError?: (error: Error) => void): Promise<MoneyVerdict>;
+/** The Evaluate call a money helper makes. Exported for tests and for integrators who build their own. */
+export declare function moneyInput(action: MoneyAction, request: PaymentRequest | BonusRequest, onError?: (error: Error) => void): EvaluateInput;
+/** Thirteen to nineteen digits passing the Luhn check: a PAN, which a PSP token is not. */
+export declare function looksLikeCardNumber(value: string): boolean;
+/**
+ * The `documentHash` key: an identity document, hashed on your side so its
+ * number never leaves your systems.
+ *
+ * Normalised first — country upper-cased, spaces, dashes and dots dropped from
+ * the number — because "AB 12-34" and "ab1234" are one passport, and two
+ * hashes for it would hide the very reuse the KYC rules look for. Pass your
+ * own `pepper` (a secret kept beside your database) so the hash cannot be
+ * reversed by trying every passport number; use the same one everywhere.
+ */
+export declare function documentHash(document: {
+    country: string;
+    type: string;
+    number: string;
+}, pepper?: string): string;
+/**
+ * The `addressHash` key: a postal address, normalised (case, punctuation and
+ * spacing folded; the postcode without spaces) and hashed on your side.
+ */
+export declare function addressHash(address: {
+    line1: string;
+    line2?: string;
+    postcode: string;
+    country: string;
+}, pepper?: string): string;
+export interface CaseWebhook {
+    readonly type: 'case.approved' | 'case.rejected' | 'case.closed';
+    readonly caseId: string;
+    readonly tenant: string;
+    readonly queue: 'review' | 'rg';
+    /** Your transaction ids (`requestId`) and our evaluation ids, so you can find what you held. */
+    readonly requests: readonly {
+        requestId: string;
+        evaluationId: string;
+        action: string;
+        amount: number | null;
+    }[];
+    readonly reasons: readonly string[];
+    readonly note: string;
+    readonly decidedAt: string;
+}
+/**
+ * Checks the `x-mshield-signature` header on a case webhook and returns the
+ * event, or undefined when the signature is wrong or older than the tolerance.
+ *
+ * Pass the raw body exactly as received — parsing and re-serialising it
+ * changes the bytes the signature covers. Answer a valid delivery with 2xx
+ * quickly; release or cancel the held transaction in your own queue.
+ */
+export declare function verifyCaseWebhook(secret: string, header: string | undefined, rawBody: string | Buffer, options?: {
+    toleranceSeconds?: number;
+    nowMs?: number;
+}): CaseWebhook | undefined;
+export {};
+//# sourceMappingURL=igaming.d.ts.map

package/dist/igaming.js

@@ -0,0 +1,173 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+const COMMON = {
+    allow: 'proceed',
+    allow_flagged: 'proceed',
+    review: 'hold',
+    challenge: 'challenge',
+    step_up: 'step_up',
+    throttle: 'retry_later',
+    deny: 'refuse',
+    ban: 'refuse',
+};
+/**
+ * Per action, where it differs from the common mapping. A deposit under review
+ * is taken: holding a player's incoming money helps nobody, and the case is
+ * decided before any of it can be withdrawn.
+ */
+const BY_ACTION = {
+    deposit: { review: 'proceed' },
+    withdraw: {},
+    bonus_claim: {},
+};
+const ADVICE = {
+    deposit: {
+        proceed: 'Take the deposit.',
+        hold: 'Hold the deposit until the case is decided.',
+        challenge: 'Show the challenge, then retry the deposit with the solution.',
+        step_up: 'Ask for 3-D Secure or your own stronger check before taking it.',
+        retry_later: 'Too many attempts: ask the player to try again shortly.',
+        refuse: 'Decline the deposit.',
+    },
+    withdraw: {
+        proceed: 'Pay out.',
+        hold: 'Keep the withdrawal pending. Release it on case.approved; cancel it and return the funds on case.rejected.',
+        challenge: 'Show the challenge, then retry the withdrawal with the solution.',
+        step_up: 'Ask for a second factor before paying out.',
+        retry_later: 'Too many attempts: ask the player to try again shortly.',
+        refuse: 'Decline the withdrawal; the funds stay in the account.',
+    },
+    bonus_claim: {
+        proceed: 'Credit the bonus.',
+        hold: 'Do not credit the bonus yet. Credit it on case.approved; withdraw the offer on case.rejected.',
+        challenge: 'Show the challenge, then retry the claim with the solution.',
+        step_up: 'Ask for a second factor or verification before crediting it.',
+        retry_later: 'Too many attempts: ask the player to try again shortly.',
+        refuse: 'Do not credit the bonus.',
+    },
+};
+/** The recommended handling of a decision on a money action. */
+export function handlingFor(action, decision) {
+    return BY_ACTION[action][decision] ?? COMMON[decision];
+}
+export async function evaluateMoney(shield, action, request, onError) {
+    const verdict = await shield.evaluate(moneyInput(action, request, onError));
+    const handling = handlingFor(action, verdict.decision);
+    return { verdict, handling, advice: ADVICE[action][handling] };
+}
+/** The Evaluate call a money helper makes. Exported for tests and for integrators who build their own. */
+export function moneyInput(action, request, onError) {
+    const payment = 'amount' in request ? request : undefined;
+    const bonus = 'bonusType' in request ? request : undefined;
+    let paymentMethod = payment?.paymentMethod;
+    if (paymentMethod !== undefined && looksLikeCardNumber(paymentMethod)) {
+        // The gateway refuses a request carrying a card number outright, and the
+        // client would then fail open with no decision at all. Dropping the key
+        // keeps the decision; the error says why the card was not counted.
+        onError?.(new Error(`${action}: paymentMethod looks like a card number and was not sent; send the PSP's card fingerprint or token`));
+        paymentMethod = undefined;
+    }
+    const keys = {
+        ...request.keys,
+        username: request.account,
+        ...(request.sessionId === undefined ? {} : { sessionId: request.sessionId }),
+        ...(paymentMethod === undefined ? {} : { paymentMethod }),
+        ...(payment?.paymentBin === undefined ? {} : { paymentBin: payment.paymentBin }),
+        ...(bonus?.promoCode === undefined ? {} : { promoCode: bonus.promoCode }),
+        ...(bonus?.referrerId === undefined ? {} : { referrerId: bonus.referrerId }),
+        ...(bonus?.affiliateId === undefined ? {} : { affiliateId: bonus.affiliateId }),
+    };
+    const amount = payment?.amount ?? bonus?.value;
+    const attributes = {
+        ...request.attributes,
+        ...(amount === undefined ? {} : { amount }),
+        ...(payment?.currency === undefined ? {} : { currency: payment.currency }),
+        ...(payment?.paymentType === undefined ? {} : { paymentType: payment.paymentType }),
+        ...(payment?.paymentCountry === undefined ? {} : { paymentCountry: payment.paymentCountry.toUpperCase() }),
+        ...(bonus === undefined ? {} : { bonusType: bonus.bonusType }),
+    };
+    return {
+        action,
+        requestId: request.transactionId,
+        keys,
+        attributes,
+        ...(request.token === undefined ? {} : { token: request.token }),
+        ...(request.ip === undefined ? {} : { ip: request.ip }),
+        ...(request.network === undefined ? {} : { network: request.network }),
+        ...(request.context === undefined ? {} : { context: request.context }),
+    };
+}
+/** Thirteen to nineteen digits passing the Luhn check: a PAN, which a PSP token is not. */
+export function looksLikeCardNumber(value) {
+    const digits = value.replace(/[\s-]/g, '');
+    if (!/^\d{13,19}$/.test(digits))
+        return false;
+    let sum = 0;
+    for (let i = 0; i < digits.length; i += 1) {
+        let d = Number(digits[digits.length - 1 - i]);
+        if (i % 2 === 1) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+    }
+    return sum % 10 === 0;
+}
+/* ── Hashing what Magic Shield must not see ─────────────────────────────── */
+/**
+ * The `documentHash` key: an identity document, hashed on your side so its
+ * number never leaves your systems.
+ *
+ * Normalised first — country upper-cased, spaces, dashes and dots dropped from
+ * the number — because "AB 12-34" and "ab1234" are one passport, and two
+ * hashes for it would hide the very reuse the KYC rules look for. Pass your
+ * own `pepper` (a secret kept beside your database) so the hash cannot be
+ * reversed by trying every passport number; use the same one everywhere.
+ */
+export function documentHash(document, pepper = '') {
+    const canonical = [document.country.trim().toUpperCase(), document.type.trim().toLowerCase(), document.number.replace(/[\s.\-/]/g, '').toUpperCase()].join(':');
+    return keyed(pepper, `document:${canonical}`);
+}
+/**
+ * The `addressHash` key: a postal address, normalised (case, punctuation and
+ * spacing folded; the postcode without spaces) and hashed on your side.
+ */
+export function addressHash(address, pepper = '') {
+    const fold = (s) => s.toLowerCase().replace(/[.,#'"]/g, ' ').replace(/\s+/g, ' ').trim();
+    const canonical = [fold(address.line1), fold(address.line2 ?? ''), address.postcode.replace(/\s+/g, '').toUpperCase(), address.country.trim().toUpperCase()].join('|');
+    return keyed(pepper, `address:${canonical}`);
+}
+function keyed(pepper, value) {
+    return pepper === '' ? createHash('sha256').update(value).digest('hex') : createHmac('sha256', pepper).update(value).digest('hex');
+}
+/**
+ * Checks the `x-mshield-signature` header on a case webhook and returns the
+ * event, or undefined when the signature is wrong or older than the tolerance.
+ *
+ * Pass the raw body exactly as received — parsing and re-serialising it
+ * changes the bytes the signature covers. Answer a valid delivery with 2xx
+ * quickly; release or cancel the held transaction in your own queue.
+ */
+export function verifyCaseWebhook(secret, header, rawBody, options = {}) {
+    if (header === undefined || secret === '')
+        return undefined;
+    const parts = new Map(header.split(',').map((part) => part.trim().split('=', 2)));
+    const t = Number(parts.get('t'));
+    const v1 = parts.get('v1') ?? '';
+    if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(v1))
+        return undefined;
+    const now = Math.floor((options.nowMs ?? Date.now()) / 1000);
+    if (Math.abs(now - t) > (options.toleranceSeconds ?? 300))
+        return undefined;
+    const body = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+    const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest();
+    if (!timingSafeEqual(expected, Buffer.from(v1, 'hex')))
+        return undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=igaming.js.map

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { createClient, ShieldClient, API_KEY_METADATA } from './client.js';
 export type { ShieldConfig, ShieldDefaults } from './client.js';
 export { passwordPrefix, isPasswordPrefix } from './password.js';
 export { Breaker } from './breaker.js';
+export { addressHash, documentHash, handlingFor, looksLikeCardNumber, moneyInput, verifyCaseWebhook } from './igaming.js';
+export type { BonusRequest, CaseWebhook, Handling, MoneyAction, MoneyVerdict, PaymentRequest } from './igaming.js';
 export type { BreakerOptions } from './breaker.js';
-export type { ChallengeOffer, ChallengeSolution, DecisionName, EvaluateInput, FeedbackInput, Identifiers, LimitCheckInput, LimitState, LimitVerdict, NetworkContext, OutcomeDetails, OutcomeName, Reason, TrustDeviceInput, TrustedDevice, Verdict, WouldHave, } from './types.js';
+export type { ChallengeOffer, ChallengeSolution, DecisionName, EvaluateInput, FeedbackInput, Identifiers, LimitCheckInput, LimitState, LimitVerdict, NetworkContext, OutcomeDetails, OutcomeName, Reason, TransactionAttributes, TrustDeviceInput, TrustedDevice, Verdict, WouldHave, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createClient, ShieldClient, API_KEY_METADATA } from './client.js';
 export { passwordPrefix, isPasswordPrefix } from './password.js';
 export { Breaker } from './breaker.js';
+export { addressHash, documentHash, handlingFor, looksLikeCardNumber, moneyInput, verifyCaseWebhook } from './igaming.js';
 //# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -20,7 +20,13 @@
  * mapping to the wire enum is in `decisions.ts` and is the only place either
  * spelling appears.
  */
-export type DecisionName = 'allow' | 'allow_flagged' | 'challenge' | 'step_up' | 'throttle' | 'deny' | 'ban';
+export type DecisionName = 'allow' | 'allow_flagged'
+/**
+ * Let it proceed or hold it — your choice per action — while an analyst
+ * looks. For a withdrawal: hold it, and release or cancel it when the case
+ * webhook arrives.
+ */
+ | 'review' | 'challenge' | 'step_up' | 'throttle' | 'deny' | 'ban';
 /**
  * The eleven outcomes, in the short form `docs/api.md` §5 publishes.
  *
@@ -56,6 +62,47 @@ export interface Identifiers {
      * identifies a spraying campaign and identifies no individual.
      */
     readonly passwordSha1Prefix?: string;
+    /**
+     * The card fingerprint or token your PSP gives you, or a wallet id — never
+     * the card number. A value that looks like one is refused by the gateway.
+     */
+    readonly paymentMethod?: string;
+    /** The first six or eight digits of the card: the issuing bank, not the person. */
+    readonly paymentBin?: string;
+    readonly promoCode?: string;
+    readonly affiliateId?: string;
+    /** A hash of the identity document number, computed on your side. */
+    readonly documentHash?: string;
+    /** A hash of the normalised postal address, computed on your side. */
+    readonly addressHash?: string;
+    /** The account that referred this one. */
+    readonly referrerId?: string;
+    readonly custom?: Readonly<Record<string, string>>;
+}
+/**
+ * What the transaction is, for the money and account actions. Every field is
+ * optional; a rule that reads one you did not send abstains rather than
+ * matching.
+ */
+export interface TransactionAttributes {
+    /** In your base currency, so one rule compares deposits in any currency. */
+    readonly amount?: number;
+    /** What the player paid in, for the record. */
+    readonly currency?: string;
+    readonly paymentType?: 'card' | 'prepaid' | 'e_wallet' | 'crypto' | 'bank' | (string & {});
+    /** ISO 3166 alpha-2 of the payment instrument. */
+    readonly paymentCountry?: string;
+    readonly bonusType?: string;
+    readonly gameCategory?: string;
+    readonly stake?: number;
+    readonly odds?: number;
+    readonly kycStatus?: 'none' | 'pending' | 'verified' | 'rejected' | (string & {});
+    readonly selfExcluded?: boolean;
+    readonly depositLimitReached?: boolean;
+    /** For `profile_change`: email, phone, password or address. */
+    readonly changed?: string;
+    /** The player's age in whole years, from the date of birth you hold — never the date itself. */
+    readonly age?: number;
     readonly custom?: Readonly<Record<string, string>>;
 }
 /** What the socket revealed, when something in front of you observed it. */
@@ -69,7 +116,11 @@ export interface NetworkContext {
     readonly headers?: Readonly<Record<string, string>>;
 }
 export interface EvaluateInput {
-    /** `'login'`, `'signup'`, `'checkout'` — yours to name. */
+    /**
+     * `'login'`, `'signup'`, `'deposit'`, `'withdraw'`, `'bonus_claim'`… The
+     * standard names are what the shipped rules match; your own names work too,
+     * and can be mapped to the standard ones in the console.
+     */
     readonly action: string;
     /**
      * The sealed string the web SDK returned.
@@ -102,6 +153,8 @@ export interface EvaluateInput {
     readonly verboseReasons?: boolean;
     /** Free-form context the rules can read. `origin` is the one that matters. */
     readonly context?: Readonly<Record<string, string>>;
+    /** Amount, payment type, KYC status… for deposit, withdraw, bonus_claim and the like. */
+    readonly attributes?: TransactionAttributes;
 }
 export interface ChallengeSolution {
     readonly blob: string;
@@ -202,7 +255,7 @@ export type Verdict = (VerdictBase & {
     readonly decision: 'throttle';
     readonly retryAfterMs: number;
 }) | (VerdictBase & {
-    readonly decision: 'allow' | 'allow_flagged' | 'step_up' | 'deny' | 'ban';
+    readonly decision: 'allow' | 'allow_flagged' | 'review' | 'step_up' | 'deny' | 'ban';
 });
 export interface FeedbackInput {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magield/node",
-  "version": "0.7.1",
+  "version": "0.8.2",
   "description": "Magic Shield backend SDK",
   "license": "SEE LICENSE IN LICENSE",
   "files": [
@@ -23,14 +23,14 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@grpc/grpc-js": "^1.12.4",
-    "@magield/proto": "0.7.1"
+    "@magield/proto": "0.8.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "@magield/storage": "0.7.1",
-    "@magield/gateway": "0.7.1"
+    "@magield/gateway": "0.8.2",
+    "@magield/storage": "0.8.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",