@alogram/payrisk 0.1.6

package/dist/exceptions.d.ts

@@ -0,0 +1,24 @@
+export declare class AlogramError extends Error {
+    status?: number | undefined;
+    body?: any | undefined;
+    constructor(message: string, status?: number | undefined, body?: any | undefined);
+}
+export declare class AuthenticationError extends AlogramError {
+    constructor(message: string, status?: number, body?: any);
+}
+export declare class RateLimitError extends AlogramError {
+    constructor(message: string, status?: number, body?: any);
+}
+export declare class ValidationError extends AlogramError {
+    constructor(message: string, status?: number, body?: any);
+}
+export declare class InternalServerError extends AlogramError {
+    constructor(message: string, status?: number, body?: any);
+}
+/**
+ * 🔒 Thrown when an SDK method is called using a key that does not have the required trust scope.
+ * (e.g., calling checkRisk with a pk_... key)
+ */
+export declare class ScopedAccessError extends AlogramError {
+    constructor(message: string);
+}

package/dist/exceptions.js

@@ -0,0 +1,59 @@
+"use strict";
+// Copyright (c) 2025 Alogram Inc.
+// All rights reserved.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopedAccessError = exports.InternalServerError = exports.ValidationError = exports.RateLimitError = exports.AuthenticationError = exports.AlogramError = void 0;
+class AlogramError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'AlogramError';
+        Object.setPrototypeOf(this, AlogramError.prototype);
+    }
+}
+exports.AlogramError = AlogramError;
+class AuthenticationError extends AlogramError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = 'AuthenticationError';
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class RateLimitError extends AlogramError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = 'RateLimitError';
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+exports.RateLimitError = RateLimitError;
+class ValidationError extends AlogramError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = 'ValidationError';
+        Object.setPrototypeOf(this, ValidationError.prototype);
+    }
+}
+exports.ValidationError = ValidationError;
+class InternalServerError extends AlogramError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = 'InternalServerError';
+        Object.setPrototypeOf(this, InternalServerError.prototype);
+    }
+}
+exports.InternalServerError = InternalServerError;
+/**
+ * 🔒 Thrown when an SDK method is called using a key that does not have the required trust scope.
+ * (e.g., calling checkRisk with a pk_... key)
+ */
+class ScopedAccessError extends AlogramError {
+    constructor(message) {
+        super(message, 403);
+        this.name = 'ScopedAccessError';
+        Object.setPrototypeOf(this, ScopedAccessError.prototype);
+    }
+}
+exports.ScopedAccessError = ScopedAccessError;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './client';
+export * from './exceptions';
+export * from './webhooks';
+export * from './testing';
+export * from './_generated/models/index';

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+// Copyright (c) 2025 Alogram Inc.
+// All rights reserved.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client"), exports);
+__exportStar(require("./exceptions"), exports);
+__exportStar(require("./webhooks"), exports);
+__exportStar(require("./testing"), exports);
+__exportStar(require("./_generated/models/index"), exports);

package/dist/testing.d.ts

@@ -0,0 +1,24 @@
+import { DecisionResponse } from './_generated';
+/**
+ * 🛠️ **MockRiskClient**
+ *
+ * A zero-dependency mock implementation of the Alogram Risk Client for local testing.
+ */
+export declare class MockRiskClient {
+    private _calls;
+    private _queuedResponses;
+    private _defaultDecision;
+    private _defaultScore;
+    private _delayMs;
+    setDefaultDecision(decision: string, score?: number): void;
+    private getTimestamp;
+    queueDecision(decision: string, score?: number, reason?: string): void;
+    queueError(error: Error): void;
+    setDelay(ms: number): void;
+    get callCount(): number;
+    get calls(): Array<any>;
+    private _handleCall;
+    checkRisk(request: any): Promise<DecisionResponse>;
+    ingestSignals(request: any): Promise<void>;
+    ingestEvent(event: any): Promise<void>;
+}

package/dist/testing.js

@@ -0,0 +1,100 @@
+"use strict";
+// Copyright (c) 2025 Alogram Inc.
+// All rights reserved.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockRiskClient = void 0;
+/**
+ * 🛠️ **MockRiskClient**
+ *
+ * A zero-dependency mock implementation of the Alogram Risk Client for local testing.
+ */
+class MockRiskClient {
+    constructor() {
+        this._calls = [];
+        this._queuedResponses = [];
+        this._defaultDecision = 'approve';
+        this._defaultScore = 0.1;
+        this._delayMs = 0;
+    }
+    setDefaultDecision(decision, score = 0.1) {
+        this._defaultDecision = decision.toLowerCase();
+        this._defaultScore = score;
+    }
+    getTimestamp() {
+        return new Date().toISOString();
+    }
+    queueDecision(decision, score = 0.1, reason) {
+        const resp = {
+            assessmentId: `mock-${Math.random().toString(36).substring(2, 14)}`,
+            decision: decision.toLowerCase(),
+            decisionAt: this.getTimestamp(),
+            riskScore: score,
+            fraudScore: {
+                riskLevel: 'low',
+                score: score,
+                explanation: 'Mocked response',
+            },
+            reasons: reason ? [{
+                    code: 'MOCK_CODE',
+                    category: 'behavior',
+                    displayName: 'Mock Reason',
+                    description: reason,
+                }] : [],
+        };
+        this._queuedResponses.push(resp);
+    }
+    queueError(error) {
+        this._queuedResponses.push(error);
+    }
+    setDelay(ms) {
+        this._delayMs = ms;
+    }
+    get callCount() {
+        return this._calls.length;
+    }
+    get calls() {
+        return this._calls;
+    }
+    async _handleCall(method, request) {
+        this._calls.push({ method, request, timestamp: Date.now() });
+        if (this._delayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, this._delayMs));
+        }
+        if (this._queuedResponses.length > 0) {
+            const item = this._queuedResponses.shift();
+            if (item instanceof Error) {
+                throw item;
+            }
+            return item;
+        }
+        return undefined;
+    }
+    async checkRisk(request) {
+        const res = await this._handleCall('checkRisk', request);
+        if (res)
+            return res;
+        return {
+            assessmentId: `mock-${Math.random().toString(36).substring(2, 14)}`,
+            decision: this._defaultDecision,
+            decisionAt: this.getTimestamp(),
+            riskScore: this._defaultScore,
+            fraudScore: {
+                riskLevel: 'low',
+                score: this._defaultScore,
+            },
+            reasons: [{
+                    code: 'DEFAULT',
+                    category: 'behavior',
+                    displayName: 'Default',
+                    description: 'default_mock_response',
+                }],
+        };
+    }
+    async ingestSignals(request) {
+        await this._handleCall('ingestSignals', request);
+    }
+    async ingestEvent(event) {
+        await this._handleCall('ingestEvent', event);
+    }
+}
+exports.MockRiskClient = MockRiskClient;

package/dist/webhooks.d.ts

@@ -0,0 +1,10 @@
+export declare class WebhookVerifier {
+    /**
+     * Utility to verify the authenticity of webhooks sent by Alogram.
+     *
+     * @param payload The raw string or Buffer of the request body.
+     * @param signature The value of the 'x-alogram-signature' header.
+     * @param secret Your Alogram Webhook Secret.
+     */
+    static verify(payload: string | Buffer, signature: string, secret: string): boolean;
+}

package/dist/webhooks.js

@@ -0,0 +1,32 @@
+"use strict";
+// Copyright (c) 2025 Alogram Inc.
+// All rights reserved.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerifier = void 0;
+const crypto_1 = require("crypto");
+const exceptions_1 = require("./exceptions");
+class WebhookVerifier {
+    /**
+     * Utility to verify the authenticity of webhooks sent by Alogram.
+     *
+     * @param payload The raw string or Buffer of the request body.
+     * @param signature The value of the 'x-alogram-signature' header.
+     * @param secret Your Alogram Webhook Secret.
+     */
+    static verify(payload, signature, secret) {
+        if (!signature || !secret) {
+            throw new exceptions_1.ValidationError('Missing signature or secret');
+        }
+        const expectedSignature = (0, crypto_1.createHmac)('sha256', secret)
+            .update(payload)
+            .digest('hex');
+        // Use timing-safe comparison to prevent timing attacks
+        const bufferExpected = Buffer.from(expectedSignature, 'utf8');
+        const bufferActual = Buffer.from(signature, 'utf8');
+        if (bufferExpected.length !== bufferActual.length || !(0, crypto_1.timingSafeEqual)(bufferExpected, bufferActual)) {
+            throw new exceptions_1.ValidationError('Invalid webhook signature');
+        }
+        return true;
+    }
+}
+exports.WebhookVerifier = WebhookVerifier;

package/examples/asyncSignalIngestion.ts

@@ -0,0 +1,52 @@
+// Copyright (c) 2025 Alogram Inc.
+// Example: Async Signal Ingestion
+// 
+// This example shows how to ingest behavioral signals asynchronously
+// using standard Promise patterns in TypeScript.
+
+import { AlogramRiskClient, SignalsRequest } from '@alogram/payrisk';
+
+const client = new AlogramRiskClient({
+  baseUrl: 'https://api.alogram.ai',
+  apiKey: 'sk_test_...'
+});
+
+/**
+ * Simulates a background signal sender.
+ * In a real application, you might use a dedicated queue or worker.
+ */
+async function sendSignalInBackground(userId: string, type: 'page_view' | 'feature_use') {
+  const request: SignalsRequest = {
+    signalType: 'interaction',
+    entities: {
+      tenantId: 'tid_123',
+      clientId: 'web_frontend',
+      endCustomerId: userId
+    },
+    interactions: [
+      {
+        interactionType: type,
+        timestamp: new Date().toISOString(),
+        locationId: 'loc_browser'
+      }
+    ]
+  };
+
+  try {
+    // Note: We don't await this in the main thread to keep UI responsive
+    await client.ingestSignals(request);
+    console.log(`✅ Signal ${type} ingested for ${userId}`);
+  } catch (e) {
+    console.error(`❌ Signal ingestion failed: ${e}`);
+  }
+}
+
+// Simulated Express/Next.js handler
+export function onUserClick(userId: string) {
+  console.log(`👤 User ${userId} clicked a button.`);
+  
+  // Fire and forget - don't await the result
+  sendSignalInBackground(userId, 'feature_use');
+  
+  return { status: 'success' };
+}

package/examples/checkRisk.ts

@@ -0,0 +1,26 @@
+import { AlogramRiskClient } from '@alogram/payrisk';
+
+async function main() {
+  const client = new AlogramRiskClient({
+    baseUrl: 'https://api.alogram.ai',
+    apiKey: 'sk_test_12345'
+  });
+
+  const response = await client.checkRisk({
+    eventType: 'purchase',
+    entities: {
+      tenantId: 'tid_test',
+      clientId: 'cid_test',
+      endCustomerId: 'ecid_test'
+    },
+    purchase: {
+      amount: 10.50,
+      currency: 'USD',
+      transactionId: 'tx_test_123'
+    }
+  });
+
+  console.log('Risk Decision:', response.decision);
+}
+
+main().catch(console.error);

package/examples/productionErrorHandling.ts

@@ -0,0 +1,52 @@
+// Copyright (c) 2025 Alogram Inc.
+// Example: Production Error Handling
+//
+// Demonstrates robust error handling and the "Fail-Open" strategy in TypeScript.
+
+import { 
+  AlogramRiskClient, 
+  ValidationError, 
+  AuthenticationError, 
+  RateLimitError,
+  InternalServerError,
+  CheckRequest
+} from '@alogram/payrisk';
+
+const client = new AlogramRiskClient({
+  baseUrl: 'https://api.alogram.ai',
+  apiKey: 'sk_test_...'
+});
+
+async function processPayment(request: CheckRequest) {
+  try {
+    const decision = await client.checkRisk(request);
+    
+    if (decision.decision === 'decline') {
+      return { status: 'blocked', reason: decision.reasons };
+    }
+    
+    return { status: 'approved', score: decision.riskScore };
+
+  } catch (e) {
+    if (e instanceof AuthenticationError) {
+      // Logic error: Your keys are wrong. Notify Ops.
+      console.error('🚨 AUTH FAILURE: Check API Keys');
+      throw e;
+    }
+
+    if (e instanceof ValidationError) {
+      // Integration error: You sent bad data.
+      console.error('❌ INVALID DATA:', e.message);
+      return { status: 'error', message: 'Internal validation failed' };
+    }
+
+    if (e instanceof RateLimitError || e instanceof InternalServerError) {
+      // System issues: These were already retried by the SDK.
+      // STRATEGY: Fail-Open. Don't block the user if Alogram is down.
+      console.warn('⚠️ SYSTEM DEGRADED: Allowing via fail-open');
+      return { status: 'approved', note: 'manual_review_required' };
+    }
+
+    throw e;
+  }
+}

package/examples/webhookVerification.ts

@@ -0,0 +1,29 @@
+// Copyright (c) 2025 Alogram Inc.
+// Example: Webhook Verification
+//
+// Secures your Node.js endpoint by verifying Alogram's cryptographic signatures.
+
+import { WebhookVerifier } from '@alogram/payrisk';
+
+// In a real app, this comes from process.env
+const WEBHOOK_SECRET = 'whsec_...';
+
+/**
+ * Example handler for an Express.js route
+ */
+export async function handleWebhook(req: any, res: any) {
+  const signature = req.headers['x-alogram-signature'];
+  const rawBody = req.body; // Ensure you have access to the raw buffer
+
+  try {
+    WebhookVerifier.verify(rawBody, signature, WEBHOOK_SECRET);
+    
+    console.log('✅ Webhook Verified!');
+    // Handle the event (e.g. chargeback.updated)
+    
+    res.status(200).send('OK');
+  } catch (e) {
+    console.error('🛑 Invalid Signature:', e);
+    res.status(401).send('Unauthorized');
+  }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@alogram/payrisk",
+  "version": "0.1.6",
+  "description": "The official 'Smart' TypeScript client for the Alogram Payrisk API.",
+  "author": "Alogram Inc. <support@alogram.ai>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alogram/alogram-typescript.git"
+  },
+  "homepage": "https://www.alogram.ai",
+  "bugs": {
+    "url": "https://github.com/alogram/alogram-typescript/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "AI.md",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/**/*.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "uuid": "^9.0.1",
+    "async-retry": "^1.3.3"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0",
+    "eslint": "^8.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@types/node": "^20.0.0",
+    "@types/uuid": "^9.0.0",
+    "@types/async-retry": "^1.4.0",
+    "@opentelemetry/api": "^1.7.0"
+  }
+}