@fraud-intercept/sdk 0.1.0 → 0.2.0

package/README.md

@@ -2,11 +2,12 @@
 
 Typed Node.js client for the Fraud Intercept **Submit Event** API (`POST /api/v1/events`).
 
-> **Note:** npm publish is not live yet. Install from this monorepo path or wait for the public registry release.
+Published on npm as [`@fraud-intercept/sdk`](https://www.npmjs.com/package/@fraud-intercept/sdk). API reference: [fraud-intercept.com/api-docs](https://fraud-intercept.com/api-docs/introduction).
 
 ## Requirements
 
 - Node.js 18+ (uses global `fetch`)
+- A Fraud Intercept API key from your brand dashboard (see [authentication](https://fraud-intercept.com/api-docs/authentication))
 
 ## Install
 
@@ -85,7 +86,52 @@ The client returns the API `data` object, including:
 - `AuthenticationError` — invalid or missing API key (401)
 - `RateLimitError` — rate limit exceeded (429)
 
-Client-side validation runs before any HTTP call (missing `eventId`, invalid `eventType`, no identifiers).
+Client-side validation runs before any HTTP call (missing `eventId`, invalid `eventType`, no identifiers, invalid `creditCardHash` format).
+
+## Payment network matching
+
+Cross-brand payment linking requires **FI Payment Fingerprint v1** — the same 64-character hash for the same funding PAN across all brands on the network.
+
+### Algorithm
+
+1. Use the **funding PAN** (primary account number) only — not wallet DPANs or processor tokens.
+2. Strip all non-digit characters from the PAN string.
+3. Validate the result is **13–19** digits.
+4. Compute `SHA-256` over the **UTF-8** encoding of that digit string.
+5. Send the digest as **lowercase hexadecimal**, exactly **64** characters, in `creditCardHash`.
+
+Do **not** include expiry, CVV, cardholder name, billing ZIP, or merchant-specific salts.
+
+### Reference vector
+
+| Input PAN (digits only) | Fingerprint v1 |
+|-------------------------|----------------|
+| `4111111111111111` | `9bbef19476623ca56c17da75fd57734dbf82530686043a6e491c6d71befe8f6e` |
+
+Use the SDK helpers to compute or validate hashes:
+
+```typescript
+import {
+  hashCreditCardPan,
+  FI_PAYMENT_FINGERPRINT_V1_REFERENCE_HASH,
+  validateCreditCardHash,
+} from '@fraud-intercept/sdk'
+
+const fingerprint = hashCreditCardPan('4111 1111 1111 1111')
+// → 9bbef19476623ca56c17da75fd57734dbf82530686043a6e491c6d71befe8f6e
+```
+
+### Anti-patterns (will not network-match)
+
+These identifiers **will not** correlate with other brands in the identity graph:
+
+- Payment processor tokens / network tokens
+- Apple Pay / Google Pay device account numbers (DPANs)
+- `HMAC-SHA256(PAN, merchant_secret)` or other per-merchant salted hashes
+- BIN + last4 only (ambiguous, not a PAN fingerprint)
+- Prefixed digests such as `sha256:...` (rejected by the API)
+
+Full contract: [Payment fingerprint — API docs](https://fraud-intercept.com/api-docs/endpoints/events#payment-fingerprint-v1).
 
 ## Development
 

package/dist/client.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FraudIntercept = void 0;
 const types_1 = require("./types");
 const errors_1 = require("./errors");
+const credit_card_fingerprint_1 = require("./credit-card-fingerprint");
 const DEFAULT_BASE_URL = 'https://fraud-intercept.com';
 const DEFAULT_TIMEOUT = 10000;
 const DEFAULT_RETRIES = 2;
@@ -43,6 +44,12 @@ class FraudIntercept {
         if (!request.email && !request.phone && !request.creditCardHash) {
             throw new errors_1.FraudInterceptError('At least one identifier (email, phone, or creditCardHash) is required', 400, 'VALIDATION_ERROR');
         }
+        if (request.creditCardHash) {
+            const cc = (0, credit_card_fingerprint_1.parseCreditCardHashField)(request.creditCardHash, 'creditCardHash');
+            if (cc.error) {
+                throw new errors_1.FraudInterceptError(cc.error, 400, 'VALIDATION_ERROR');
+            }
+        }
     }
     async requestWithRetry(path, body, idempotencyKey, attempt = 0) {
         try {

package/dist/credit-card-fingerprint.d.ts

@@ -0,0 +1,12 @@
+export declare const FI_PAYMENT_FINGERPRINT_VERSION: "v1";
+/** SHA-256("4111111111111111") — use in docs and tests */
+export declare const FI_PAYMENT_FINGERPRINT_V1_REFERENCE_HASH = "9bbef19476623ca56c17da75fd57734dbf82530686043a6e491c6d71befe8f6e";
+export declare function normalizePanDigits(pan: string): string;
+export declare function hashCreditCardPan(pan: string): string;
+export declare function normalizeCreditCardHash(input: string | null | undefined): string | null;
+export declare function validateCreditCardHash(hash: string): boolean;
+export declare function creditCardHashFieldError(fieldName: 'creditCardHash' | 'credit_card_hash'): string;
+export declare function parseCreditCardHashField(input: unknown, fieldName?: 'creditCardHash' | 'credit_card_hash'): {
+    value: string | null;
+    error?: string;
+};

package/dist/credit-card-fingerprint.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FI_PAYMENT_FINGERPRINT_V1_REFERENCE_HASH = exports.FI_PAYMENT_FINGERPRINT_VERSION = void 0;
+exports.normalizePanDigits = normalizePanDigits;
+exports.hashCreditCardPan = hashCreditCardPan;
+exports.normalizeCreditCardHash = normalizeCreditCardHash;
+exports.validateCreditCardHash = validateCreditCardHash;
+exports.creditCardHashFieldError = creditCardHashFieldError;
+exports.parseCreditCardHashField = parseCreditCardHashField;
+const crypto_1 = require("crypto");
+exports.FI_PAYMENT_FINGERPRINT_VERSION = 'v1';
+/** SHA-256("4111111111111111") — use in docs and tests */
+exports.FI_PAYMENT_FINGERPRINT_V1_REFERENCE_HASH = '9bbef19476623ca56c17da75fd57734dbf82530686043a6e491c6d71befe8f6e';
+const PAN_DIGITS_REGEX = /^[0-9]{13,19}$/;
+const FINGERPRINT_REGEX = /^[a-f0-9]{64}$/;
+const SHA256_PREFIX_REGEX = /^sha256:/i;
+function normalizePanDigits(pan) {
+    return pan.replace(/\D/g, '');
+}
+function hashCreditCardPan(pan) {
+    const digits = normalizePanDigits(pan);
+    if (!PAN_DIGITS_REGEX.test(digits)) {
+        throw new Error('PAN must be 13–19 digits after removing non-digits');
+    }
+    return (0, crypto_1.createHash)('sha256').update(digits, 'utf8').digest('hex');
+}
+function normalizeCreditCardHash(input) {
+    if (input == null)
+        return null;
+    const trimmed = String(input).trim();
+    if (!trimmed)
+        return null;
+    if (SHA256_PREFIX_REGEX.test(trimmed))
+        return null;
+    return trimmed.replace(/\s+/g, '').toLowerCase();
+}
+function validateCreditCardHash(hash) {
+    return FINGERPRINT_REGEX.test(hash);
+}
+function creditCardHashFieldError(fieldName) {
+    return `${fieldName} must be a 64-character lowercase SHA-256 hex fingerprint (FI Payment Fingerprint v1). See API docs: Payment fingerprint.`;
+}
+function parseCreditCardHashField(input, fieldName = 'creditCardHash') {
+    if (input == null)
+        return { value: null };
+    const raw = String(input).trim();
+    if (!raw)
+        return { value: null };
+    if (SHA256_PREFIX_REGEX.test(raw)) {
+        return { value: null, error: creditCardHashFieldError(fieldName) };
+    }
+    const normalized = normalizeCreditCardHash(raw);
+    if (!normalized || !validateCreditCardHash(normalized)) {
+        return { value: null, error: creditCardHashFieldError(fieldName) };
+    }
+    return { value: normalized };
+}

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export { FraudIntercept } from './client';
 export { FraudInterceptError, AuthenticationError, RateLimitError } from './errors';
 export type { EventType, SubmitEventRequest, SubmitEventOptions, SubmitEventResponse, MultiAccountMetadata, EventHelperRequest, FraudInterceptConfig, CheckRegistrationRequest, CheckRegistrationResponse, CheckLoginRequest, CheckLoginResponse, CheckDepositRequest, CheckDepositResponse, CheckWithdrawalRequest, CheckWithdrawalResponse, Flag, TriggeredRule, MatchedThreat, MatchedFraudster, AthleteMatch, DeviceInfo, MultiAccountInfo, DetectionCoverage, ResponseNote, } from './types';
 export { EVENT_TYPES } from './types';
+export { FI_PAYMENT_FINGERPRINT_VERSION, FI_PAYMENT_FINGERPRINT_V1_REFERENCE_HASH, hashCreditCardPan, normalizeCreditCardHash, validateCreditCardHash, parseCreditCardHashField, } from './credit-card-fingerprint';
 export { FraudIntercept as default } from './client';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = exports.EVENT_TYPES = exports.RateLimitError = exports.AuthenticationError = exports.FraudInterceptError = exports.FraudIntercept = void 0;
+exports.default = exports.parseCreditCardHashField = exports.validateCreditCardHash = exports.normalizeCreditCardHash = exports.hashCreditCardPan = exports.FI_PAYMENT_FINGERPRINT_V1_REFERENCE_HASH = exports.FI_PAYMENT_FINGERPRINT_VERSION = exports.EVENT_TYPES = exports.RateLimitError = exports.AuthenticationError = exports.FraudInterceptError = exports.FraudIntercept = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "FraudIntercept", { enumerable: true, get: function () { return client_1.FraudIntercept; } });
 var errors_1 = require("./errors");
@@ -9,5 +9,12 @@ Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: f
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
 var types_1 = require("./types");
 Object.defineProperty(exports, "EVENT_TYPES", { enumerable: true, get: function () { return types_1.EVENT_TYPES; } });
+var credit_card_fingerprint_1 = require("./credit-card-fingerprint");
+Object.defineProperty(exports, "FI_PAYMENT_FINGERPRINT_VERSION", { enumerable: true, get: function () { return credit_card_fingerprint_1.FI_PAYMENT_FINGERPRINT_VERSION; } });
+Object.defineProperty(exports, "FI_PAYMENT_FINGERPRINT_V1_REFERENCE_HASH", { enumerable: true, get: function () { return credit_card_fingerprint_1.FI_PAYMENT_FINGERPRINT_V1_REFERENCE_HASH; } });
+Object.defineProperty(exports, "hashCreditCardPan", { enumerable: true, get: function () { return credit_card_fingerprint_1.hashCreditCardPan; } });
+Object.defineProperty(exports, "normalizeCreditCardHash", { enumerable: true, get: function () { return credit_card_fingerprint_1.normalizeCreditCardHash; } });
+Object.defineProperty(exports, "validateCreditCardHash", { enumerable: true, get: function () { return credit_card_fingerprint_1.validateCreditCardHash; } });
+Object.defineProperty(exports, "parseCreditCardHashField", { enumerable: true, get: function () { return credit_card_fingerprint_1.parseCreditCardHashField; } });
 var client_2 = require("./client");
 Object.defineProperty(exports, "default", { enumerable: true, get: function () { return client_2.FraudIntercept; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fraud-intercept/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Fraud Intercept SDK for real-time Digital Trust event scoring",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,18 @@
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petrovpetkov01-web/fraud-intercept.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://fraud-intercept.com/api-docs/introduction",
+  "bugs": {
+    "url": "https://github.com/petrovpetkov01-web/fraud-intercept/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": ["fraud", "digital-trust", "risk-scoring", "device-intelligence"],
   "license": "MIT",
   "devDependencies": {